This article demonstrates how to create properly-formatted and useful documentation for Mozilla interfaces. Each interface should be documented in its own article, with the article's title being the name of the interface.
Learn by example
See our sample interface document for a fictional interface that implements all the features of a complete interface reference document. This article can serve as a helpful template when documenting an interface.
A few real interfaces that demonstrate this standard include nsIFeedProcessor, nsIFeedContainer, nsIFeedTextConstruct, and nsIScriptableUnescapeHTML.
Interface reference sections
Each interface reference article has at least an introduction section (which has no heading). The introduction should provide an overview of what the interface is used for.
Following the table of contents, use the <code>IFSummary macro to describe the location and status of the interface in the source tree.
The parameters to the IFSummary macro are:
- Path of the IDL file defining the interface
- This is used to create a link to the interface's IDL on MXR so the reader can refer to it if they wish.
- Parent interface
- This is the name of the interface upon which the interface being documented is based. This will be turned into a link to that interface in the interface reference and displayed.
- scriptable/not scriptable
- A string indicating whether the interface is scriptable or not. You must use either "scriptable" or "not scriptable" (these are, however, case insensitive). This will be turned into an appropriate indicator in the box, colored green for scriptable interfaces or red for non-scriptable ones. The indicator will also include a link to an article explaining what this means.
- Last changed in what Gecko version
- This is a string indicating the version of Gecko in which the interface was last changed. It should be a string in standard Gecko version format, such as "1.9" or "1.9.2" or even "1.9.1.6".
- Summary Optional
- A brief textual summary of what the interface does. Should be just a sentence or two. This is only optional for backward compatibility with old interface documents using the now deprecated InterfaceStatus macro (which now calls through to this one). You should always provide this.
- Version introduced Optional
- If you know the version of Gecko in which the interface was introduced, include that here. This will trigger the inclusion of a version timeline diagram showing the availability of the interface in relation to the history of Gecko.
- Version deprecated Optional
- If the interface is deprecated, include that here. This will be used when drawing the version timeline diagram.
- Version obsoleted Optional
- Similarly, if the interface is obsolete and no longer available at all, include the Gecko version in which that took effect.
- FIXME: Should describe the 'Implemented by' section here
All other sections are usually optional, but may be necessary depending on the interface. The optional sections are:
Method overview
The method overview is a table that simply lists all the method signatures for each method provided by the interface. The method's name should be a clickable link to the method description itself. Ideally, the methods should be listed in alphabetical order.
If a method supports multiple types for a given input parameter, you can list them using the format [type1, type2, ..., typeN].
Attributes
The attributes section consists of a three column table. The first column contains the names of each attribute offered by the interface. The second column indicates the types of each attribute; these types should be links for non-simple types. The third column should describe the attribute, explaining its use and providing any details needed. Please list the attributes in alphabetical order; you can sort the table after the fact by right-clicking in it; there's a "Sort Table" option in the contextual menu.
Constants
Each group of constants should have a sub-section containing a table describing the relevant constants. The table should have three columns: Constant (the names of the constants), Value (their values), and Description (descriptive text explaining the use of the constant).
Methods
The methods section provides detailed documentation for each method offered by the interface. Within the methods section should be a subsection for each method. Each method's subsection name should include closing parentheses (such as "parseAsync()" in the nsIFeedProcessor interface reference.
The methods should be listed in the same order in which they appear in the "Method overview" section.
Each method's subsection should begin with a description of what the method does, followed by the actual method signature itself. Each parameter to the method should be on a separate line for clarity.
After the method signature should come a "Parameters" subsection. In order to avoid cluttering the table of contents for the page, we use <h5>Parameters</h5> to define the Parameters subsection's heading.
The parameters are then listed with descriptions of each parameter using definition list format. If there are no parameters, write the word 'None' under the Parameters heading.
If the method has a return value, include a "Return value" subsection, using the form <h5>Return value</h5>. This subsection should simply explain the return value, its type, and if applicable its possible values.
If the method can throw exceptions, a similar "Exceptions thrown" subsection should be included, containing a definition list style list for each possible exception.
For a good example of a method section that includes all the subsections, see the nsIScriptableUnescapeHTML.parseFragment() method.
Remarks
Any general comments that apply to the interface as a whole may be placed in the Remarks section.
See also
If links to other interfaces, or to any other documents, might be helpful to the reader, these should be listed in the "See also" section.
Categorizing articles
Each article that documents an interface needs to be added to the Interfaces category by adding the "Interfaces" tag. Likewise, the article should have any other appropriate tags.
Other useful macros
Make use of commonly-used macros when appropriate, in particular, interface when linking to other interfaces, and interfacemethod when linking to a particular method of another interface.
Finding articles that need help
Look through the interface list and see if any are marked as being in the category NeedsMarkupWork. These are interfaces that we know need to be reformatted into our new layout. If you clean one up, remove the line that adds it to that category.