How to write Mozilla interface reference documentation - The MDN project 编辑

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.

Important: We no longer actively document the Mozilla-internal interfaces (most of which start with nsI) on MDN. A final decision as to where these documents should reside in the future is still under consideration; in the meantime, we generally discourage using your time to document them on MDN.

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.

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 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".

SummaryOptional

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 introducedOptional

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 deprecatedOptional

If the interface is deprecated, include that here. This will be used when drawing the version timeline diagram.

Version obsoletedOptional

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

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.

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.