Contents of some doc.odin files not getting into the documentation.

[mgavioli]

Of the 18 doc.odin files present in the core library, ca. 8 do not show up in the library documentation.

It seems this can be related to 3 elements:

• the file include a //+build ignore line or not;
• the documenting comment is before/after the package statement;
• there are blank lines between the comment and the package statement or not.

This is a summary:

package	+build ignore	before/after	blank lines	is OK?
c/frontend/tokenizer		before	☑
container/but_array		after	☑
crypto/hash		before		☑
dynlib	☑	before
encoding/endian		before		☑
encoding/hxa		before		☑
encoding/varint		before		☑
fmt		before		☑
image/netpmb		before	☑
math/big		before		☑
math/linalg		before		☑
mem		before		☑
net		before		☑
os/os2		before		inactive?
prof/spall		before		☑
sys/info	☑	before
text/i18n	☑	after	☑
text/table		before	☑

If useful, I can provide a PR fixing the proper order and (lack of) spacing, but with no semantic changes in the contents. The same should probably be done for the other libraries as well, but I limited myself to the core library, for lack of time.

I cannot assess what a //+build ignore line does in a documentation file: does the author want to document something or not?

Also, in addition to fixing the files, it is probably wise to make the documentation parser tolerant of extra blank space, as this is something which can come spontaneous; but this is the topic of another issue, I believe.

[laytan]

Nice job finding all these cases!

For text/i18n the //+build ignore can be removed I think, but in sys/info it is there to make sure the package doesn't depend on fmt, which it does do in the doc.odin file, if we want that in the docs the actual code example should be moved to another file (with the ignore comment).

I don't think we should make the parser more tolerant on the whitespace, a general idea in Odin is that doc comments can be attached to a statement by placing them right before it, and be standalone in other cases.

Another thing to note is that a lot of these doc comments aren't formatted correctly for the documentation generator either, there is a brief explanation here: https://github.com/odin-lang/pkg.odin-lang.org?tab=readme-ov-file#markup-rules about the rules.

For example, just taking the tokenizer package, it has not got the entire code example indented with a tab, this will render the first part as normal text and then the indented part as code.

Another example is the hash (and mem) package, which does get rendered currently, but looks bad. This is because it uses triple ` (which I don't think the generator looks at but could be wrong) and it doesn't indent the code blocks.

A lot of them also include links in a different way than the generator expects.

Besides just indenting you can also do something like this:

/*
Example:
    bar := foo(baz)
*/

The generator will instead of just rendering it as generic code, pick up on the example heading and actually highlight the code, you can see this in action at a lot of the math/rand procs like this one: https://pkg.odin-lang.org/core/math/rand/#float32. In general the math/rand package has the best examples of good doc comments.