Commenting IDL for better documentation

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 MDN, 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.

Don't worry!

You don't need to write perfect documentation. That is why Mozilla has a couple of writers on-staff as well as a horde of happy volunteers. We will 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 are not able to do automatically.

Comment format

Doxygen supports several comment formats; for style and consistency reasons, we use the following:

/**
 *
 */

Note the two asterisks ("**") on the first line of the comment. That lets Doxygen (and by extension, our automated documentation import tools) know that the comment should be absorbed into documentation. If you use any other format for your comments, our tools will ignore them.

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 is obvious what it means. Automatic documentation generation tools can not see what is obvious to human brains. Plus, what is obvious to you is likely not obvious to everyone.
Use Doxygen style comments only for information that is 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.
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.

Special commands

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.

Command	Details
@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 the actual name of the error constant, in all caps.
@note description	Used to include a note styled paragraph.
@remarks remark	A remark paragraph to be included in the Remarks section of the documentation. Note This is not yet supported by our documentation tool. Using it will make it easier for documenters.
@see description	Either an interface or a HTML link. Note This is not yet supported by our documentation tool. Using it will make it easier for documenters.
- or .	Used at the beginning of a comment line to indicate an unordered list item. There must be a space between the list marker and the 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. There must be a space between the list marker and the item. Nested lists should be indented from the previous level by two spaces.

Other tips

Some other helpful writing style tips that will help you make your comments cleaner and easier to read and understand:

You don't need to include what a method returns in the description. Just include the @returns line. This helps avoid repetition and keeps your comment more streamlined.
Everything in the Doxygen comment before a method, attribute, constant, or whatnot will be used as part of its description when the automatic documentation generator tool scans your IDL, so if you don't want it in the docs, you probably shouldn't put it there. Use a different format of comment instead, such as /* ... */ or even // comment.

Example

This is an example of what the Sample interface document IDL would look like:

/**
 * @brief A make-believe interface that eats and enjoys cookies. This is an
 * example of what an interface document should look like; however, it's not a
 * document about a real interface.
 *
 * @note The article's name should be "nsICookieMonster" but is not in
 * order to make it more obvious this is an example.  Also, you should add the
 * "Interfaces" tag to your article, as well as "Interfaces:Scriptable" if the
 * interface is scriptable.
 *
 * @remarks Remember, this isn't a real interface. This is where you would
 * provide additional information about the interface as necessary.
 *
 * @see nsICookie
 * @see nsICookieManager
 */

/*
 * Take note that this is not a Doxygen style comment, there is only one * on
 * the line above.
 * This means that anything I mention here will not be used to generate
 * documentation.
 *
 * To make it easier to document I have included that you can create an instance
 * of this interface by implementing: @mozilla.org/cookie-monster;1
 */
// I can also just use a comment like this here as well and it will not be used.
[scriptable, uuid(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)]
interface nsICookieMonster : nsICookieFan {

// Cookie flavor constants

/**
 * Simple sugar cookie.
 */
const integer COOKIE_FLAVOR_SUGAR = 1;

/**
 * Chocolate chip cookie.
 */
const integer COOKIE_FLAVOR_CHOCOLATE_CHIP = 2;

/**
 * Peanut butter cookie.
 */
const integer COOKIE_FLAVOR_PEANUT_BUTTER = 3;

/**
 * Chocolate cookie with chocolate chips.
 */
const integer COOKIE_FLAVOR_DOUBLE_CHOCOLATE = 4;

/**
 * An unknown type of cookie.
 */
const integer COOKIE_FLAVOR_OTHER = 0;

// Yumminess constants

/**
 * The cookie is disgusting.
 */
const integer COOKIE_NOT_YUMMY = 1;

/**
 * The cookie is good but not awesome.
 */
const integer COOKIE_SORT_OF_YUMMY = 2;

/**
 * The cookie is really, really yummy.
 */
const integer COOKIE_EXTREMELY_YUMMY = 3;

/**
 * OMG THIS IS THE BEST COOKIE EVAR!1!!1.
 */
const integer COOKIE_OMG_YUMMY = 4;

/**
 * The cookie monster's name.
 */
readonly attribute AString name;

/**
 * The cookie monster's favorite kind of cookie. Must be one of the
 * COOKIE_FLAVOR_* constants.
 */
attribute integer favoriteCookie;

/**
 * A value from 0-100 indicating how hungry the cookie monster is.
 * 0 means "stuffed to the brim with cookies" and 100 means "I'm so empty of
 * cookies! Feed me now!"
 */
attribute integer hungerLevel;

/**
 * Feeds a cookie to the cookie monster.
 * @param cookieToEat The nsICookie to eat.
 */
void eatCookie(in nsICookie cookieToEat);

/**
 * Sings the song "C is For Cookie."
 */
void sing();

/**
 * Returns a string containing a funny quote the cookie monster might say.
 *
 * @param number The saying number to return.
 *
 * @returns An AString containing the requested funny quote. If the specified
 * quote number is invalid, an exception is thrown.
 *
 * @throws NS_ERROR_FAILURE Unable to locate the requested quote.
 */
AString getFunnySaying(in integer number);

/**
 * Says something appreciative of the tastiness of the cookie in the specified
 * language.
 *
 * @param language The localization identification indicating the language in
 * which the cookie monster is to express his love of cookies.
 */
[noscript] void sayYummy(in AString language);

};

In conclusion

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.