Documentation in Mozilla

Having worked in depths of poorly documented, just plain undocumented, or, worse yet, misdocumented code, I have started taking some initiatives on documenting code. Working with db48x, we have improved some of Mozilla's documentation framework (achievable with make documentation). I'm still polishing the fine edges of bug 433206, but what's in there should be sufficient to make spiffy documentation. The other important component of fix comes from doxygen bug 535379, a simple fix that handles Mozilla's IDLs better.

There's still more to go. There should probably be an official documentation guide for mozilla or at least the components. Someone patching up SVG and dot in doxygen would be helpful, especially the annoying URI mistake.

But the important part is how to document code. At the moment, the class list is provided in a 5-by-several hundred line table containing every IDL file and all exported headers. Wondering about how to do some IO foo, but don't know where to look? Right now, your only choice is to go through this entire list, guessing at names that would produce the right magic. Ideally, however, the documentation would include separate modules that make querying easier. However, before I make a commitment, I need to investigate how namespaces interact with doxygen for best results.

So, the important question is basic documentation. Doxygen's manual is a good starting point, but I'll brush up on basics. Documentation is signified by, alternatively, /*!, /**, /*<, ///, //!. or /*<. The ones with < in the names are used for post-documentation. A comment consists of a brief description (one-sentence, punctuated by a period), followed by potentially several paragraphs of almost-HTML code (doesn't have all HTML tags). Interspersed, though typically at the end, are doxygen tags, denoted by your preference of @ or \ (the majority of code uses @, just to warn you).

To describe all the tags would be arduous and pointless. Common ones are exception (the nsresult values), note, param, and return. See should probably be more common as well. Links to other documentation can be generated by providing the fully-qualified member name, e.g. nsMsgFolderFlags::Directory. Code can be further grouped by using the name tag and @{...@}. The latter signifies a group; one can also distribute comments across multiple members using the format.

More advanced documentation that might be helpful: lists (you can use HTML tags or -, #, and indentation, to represent unordered lists, ordered lists, and nested lists in said order). Formulas can be specified in LaTeX format if you really need it. Message sequence charts can also be generated, as well as generic dot diagrams as well, in addition to the ones doxygen generates for you. But the documentation pages can never be better than the sources from which they are derived...