search

ziglang / zig

General-purpose programming language and toolchain for maintaining robust, optimal, and reusable software.
https://ziglang.org
MIT License
33.92k stars 2.48k forks source link

Add documentation about the syntax of the doc comment #19866

Open sorairolake opened 4 months ago

sorairolake commented 4 months ago

I read the Zig Language Reference, but it didn't seem to describe the syntax of the doc comment. Looking at the standard library and lib/docs/wasm/markdown.zig, it seems that the doc comment is interpreted as Markdown.

https://github.com/ziglang/zig/blob/a685ab1499d6560c523f0dbce2890dc140671e43/lib/docs/wasm/markdown.zig#L1-L125

Perhaps, I don't think this will be the same as the CommonMark specification. So I think it would be helpful to have documentation about the syntax of the doc comment (including the syntax missing and extensions).

Arnau478 commented 4 months ago

The thing is, the markdown parser in the autodoc is subject to change. Andrew has recently said that doc comments should be markdown but only if it also looks good in the source code (e.g. don't use html tags, which CommonMark allows)