Comment Format

[ytanimura]

Consider comment format. cf. knot_vec.rs by virtualritz

[ytanimura]

My opinions:

"Examples" and "Panics"

It is standard in Rust documentation that the name of the section is "Examples" even if there is only one example.

Line breaks

It is standard markdown practice to insert line breaks before and after section headings. Let me put this one on hold. I personally prefer packed source files for the following reasons:

• It makes it easier to visually compare descriptions that are in contrast on distant lines.
• I can get some idea of the complexity of the source code from the number of lines.

In any case, if we are going to add line breaks, we should do so for all files.

Bullets

I believe that markdown bullets are a personal preference. Although asterisks is the official method of description used, there is no statement to the contrary that another method is deprecated, nor does it affect the output documentation. I have seen some say that asterisks are good because they are less often seen in English text, but I do not think that makes much sense since they will eventually appear in the source code.

[virtualritz]

For Examples & Panics: I agree. I always though this is odd but you are right, it is the standard.

For the line breaks in Markdown: I haven't used an editor that didn't support folding in two decades. People bothered by (longer) comments can usually just set comments to folded on opening a source file.

For bullets: I think it doesn't matter what style you use except if at some point parts of the inline documentation should be processed by some other tool that is more picky. If that is no concern then I don't see a reason to not prefer * over - or vice versa.