Doxygen is a system of generating documentation from source code. The documentation team has tools that convert comments from the Doxygen format into the standard reference article format we use here on MDC, with certain limitations. This article will help you understand how you can format your comments to help ensure that the conversion process can be automated as much as possible in order to ensure that your interface gets properly documented.
Happily, following these recommendations will also help ensure your comments are extremely human-readable, too.
You don't need to write perfect documentation. That's why Mozilla has a couple of writers on-staff as well as a horde of happy volunteers. We'll take your comments and notes and turn them into beautiful, easy to search and read documentation. But by following the guidelines here, you can help make sure that our tools can generate a "good start" version of the documentation for your interfaces, and that the writers will be able to easily figure out what the tools aren't able to do automatically.
Doxygen requires comments to be formatted as below, and so do our conversion tools:
/** * */
Following the rules below will ensure that our tools are able to produce the best possible results, and will have the added bonus of making your comments easier to read!
- Include documentation comments for everything, even if you think it's obvious what it means. Automatic documentation generation tools can't see what's obvious to human brains. Plus, what's obvious to you is likely not obvious to everyone.
- Use Doxygen style comments only for information that's directly useful to someone using or implementing the interface. This helps keep the documentation tidy.
- Be concise and to the point. Writers will expand upon your documentation if necessary.
- Please be sure to include the names and ideally email addresses of relevant experts in the header block in the comments; writers may need to ask questions, and it's helpful to know where to find you!
- Keep in mind that people for whom English is not their native language will be reading your comments (as well as the generated documentation), so try to avoid slang and abbreviations when possible.
- If possible, avoid putting comments in the middle of the definitions of APIs.
- If an interface is used as a parameter or as the type of the value returned by a method, please use the full name of the interface in the description of the method. This will help the tools generate proper links to help make the documentation easier to read and browse through.
You can use special commands in your Doxygen comments; the ones listed below are interpreted by our tools. Using these will help generate much higher quality documentation, faster, with less human intervention required.
|@brief description||Please only use this to provide a brief description of the interface, keep it short and to the point. Do not include more than one brief per interface.|
|@param parameter description||Every parameter of a method should be documented, only use the parameter name, leave out things like [in]/[out].|
|@returns description||If the method returns something then this should be included.|
|@throws ERROR description||The error should be in all capitals.|
|@note description||Used to include a note styled paragraph.|
|- or .||Used at the beginning of a comment line to indicate an unordered list item. Nested lists should be indented from the previous level by two spaces.|
|-#||Used at the beginning of a comment line to indicate an ordered list item. Nested lists should be indented from the previous level by two spaces.|
With just a little extra help from you, the intrepid developer, the documentation team can crank out full, formatted documentation for your interface much more quickly and accurately.