MDC:Writing interface reference documentation
From MDC
This article demonstrates how to create properly-formatted and useful documentation for interfaces. Each interface should be documented in its own article, with the article's title being the name of the interface.
Contents |
[edit] 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 abide by this standard include nsIFeedProcessor, nsIFeedContainer, nsIFeedTextConstruct, and nsIScriptableUnescapeHTML.
[edit] 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. The table of contents should immediately follow this overview (to do this, place __TOC__ on a line by itself immediately following the overview).
Following the table of contents, use the {{InterfaceStatus}} template to describe the location and status of the interface in the source tree.
The parameters to the {{InterfaceStatus}} template are:
- The interface name
- The path to the IDL file for the interface (e.g. xpcom/ds/nsIObserver.idl)
- "FROZEN" or "unfrozen" depending on whether the interface is frozen or not
- The version of Mozilla in which the interface was last changed (for example "Mozilla 1.8")
- "yes" if the interface is scriptable or "no" if it is not
Finally, there should be an "Inherits from:" line listing any parent interfaces.
- Should describe the 'Implemented by' section here
All other sections are optional, and which if any of them are needed will vary from one interface to another. The optional sections are:
[edit] 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.
[edit] 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.
[edit] Constants
- Description TBD, example at
nsISupportsPriority
[edit] 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.
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 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.
[edit] Remarks
Any general comments that apply to the interface as a whole may be placed into the Remarks section.
[edit] See also
If links to other interfaces, or to any other documents, might be helpful to the reader, those should be listed in the "See also" section.
[edit] Categorizing articles
Each article that documents an interface needs to be added to the Interfaces category by including the following line at its end:
[[Category:Interfaces]]
Likewise, the article should be included in any other appropriate categories.
[edit] Other useful templates
Make use of MDC:Custom Templates when appropriate, in particular, the Template:interface when linking to other interfaces, and Template:interface-method when linking to a particular method of another interface.
[edit] 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.