View source for Jetpack/SDK/Writing Documentation


== Documenting SDK modules in MDN ==

Each module in the SDK is documented in a single "API reference" page on MDN.

=== Creating a new API reference page ===

SDK modules are divided into two sorts: high-level and low-level.

* reference pages for high level modules are created as subpages of https://developer.mozilla.org/en-US/Add-ons/SDK/High-Level_APIs/. Visit that page, click the little gear thing in the top-right, and select "New sub-page". For "title" and "slug" use the name of the module, for example "panel".

* reference pages for low level modules are created as subpages of https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/. Visit that page, click the little gear thing in the top-right, and select "New sub-page". For "title" use the path to the module from, and not including, "sdk". For example "window/utils". For "slug" choose the same thing but substitute underscores for path separators: "window_utils".

=== API reference page overall structure ===

The high-level page organization is like this:

* Module Stability
* SEO Summary
* [H2] Usage
* [H2] Globals
** [H3] Constructors
** [H3] Functions
** [H3] Properties
** [H3] Events
* [H2] SomeClassName
** [H3] Methods
** [H3] Properties
** [H3] Events
* [H2] SomeOtherClassName
** [H3] Methods
** [H3] Properties
** [H3] Events

==== Module stability ====
First there's a single word indicating the module's stability: Experimental|Unstable|Stable|Deprecated. This is marked as a "Note box" using the [https://developer.mozilla.org/en-US/docs/Project:MDN/Contributing/Editor_guide/Editing#Formatting_styles drop-down list just right of the list of headings in the WYSIWYG editor].

==== SEO summary ====
Next there's a with a very short (not much more than 20 words) summary of the module. This is marked as the "SEO summary" and will be used for 2 things:

* it appears as the page summary in results from search engines
* it might appear under a link to the page in automatically-generated listings of API reference pages

To mark the summary as an SEO summary, select it and choose "SEO Summary" from the [https://developer.mozilla.org/en-US/docs/Project:MDN/Contributing/Editor_guide/Editing#Formatting_styles drop-down list just right of the list of headings in the WYSIWYG editor].

==== Usage ====
Next goes any general intro/usage/examples verbiage. Some modules have a lot of this, some have basically none. If they have none, skip the section.

==== Globals ====
Next go global objects exported by the module, organized into four groups: Constructors, Functions, Properties, Events. Each of these categories is an H3, and each of the actual objects in one of the categories is an H4.

If a module doesn't have any objects of a given category (for example, no module-level events) then that category is omitted.

==== Classes ====
After that there's a top level section (H2) for each significant class in the module. There's a bit of flexibility in "significant". Most obviously it will include objects the the user constructs using a named exported constructor, like PageMod or Panel. But it should also include major things like Tab or (from the request module) Response, that the user doesn't construct directly.

Each section will have three H3 subsections: Methods, Properties, Events. Each actual object under there is an H4.

If a class doesn't have any objects of a given category (for example, no properties) then that category is omitted.

=== Documenting API elements ===

Every atomic API element (each constructor, function, method, property, event) is an H4. It's styled as [CODE] and given the special class "addon-sdk-api-name".

==== Constructors ====

Constructors are documented like this:

* [H4 class="addon-sdk-api-name"][CODE] Name(parameters)
* Overview text
** [H5]Parameters
** [STRONG]parameterName : parameterType
** Parameter description
**[TABLE]mandatory options
**[TABLE]optional options

First there's the title, which is an H4 with the special class "addon-sdk-api-name", styled as code. The name includes brackets and parameters, like PageMod(options).

Then there's some general overview text.

Then we document parameters under an H5 heading called "Parameters". Each parameter is documented like paramName : paramType, and is bold. That's immediately followed by the description of the parameter.

In practice, most (all?) constructors take a single options object as a parameter. In this case the description is followed by up to 2 tables:
* the first table lists mandatory options
* the second table lists optional options

Each table has three columns. The first 2 columns are labeled Name and Type. Each row documents a single option. The description here might be quite long and may include code samples (see for example https://developer.mozilla.org/en-US/Add-ons/SDK/High-Level_APIs/page-mod#PageMod%28%29).

==== Functions ====

Functions are documented like this:

*[H4 class="addon-sdk-api-name"][CODE] Name(parameters)
*Overview text
**[H5]Parameters
**[STRONG]parameterName : parameterType
**Parameter description
**[TABLE]mandatory options
**[TABLE]optional options
**[H5]Returns
**[STRONG]returnsType : [/STRONG]Return value description

First there's the title, which is an H4 with the special class "addon-sdk-api-name", styled as code. The name includes brackets and parameters, like open(options).

Then there's some general overview text.

Then we document parameters under an H5 heading called "Parameters". Each parameter is documented like paramName : paramType, and is bold. That's immediately followed by the description of the parameter.

If the function has an options object as a parameter then the options are documented in up to 2 tables:

* the first table lists mandatory options
* the second table lists optional options

Each table has three columns. The first 2 columns are labeled Name and Type. Each row documents a single option. See for example https://developer.mozilla.org/en-US/Add-ons/SDK/High-Level_APIs/tabs#open%28%29.

Finally, if the function returns a value, there's another H5 called "Returns". Immediately after that is the type of the return value in bold, and immediately after that is the description.

==== Properties ====
Properties are documented like this:

* [H4 class="addon-sdk-api-name"][CODE] Name
* Description
** [H5]Parameters
** [STRONG]parameterName : parameterType
** Parameter description

First there's the title, which is an H4 with the special class "addon-sdk-api-name", styled as code. The text is "propertyName : type".

Then there's a description.

==== Events ====

Functions are documented like this:

* [H4 class="addon-sdk-api-name"][CODE] Name
* Overview text
** [H5]Arguments
** [STRONG]argumentType : [/STRONG] Argument description

First there's the title, which is an H4 with the special class "addon-sdk-api-name", styled as code. The name is just the name of the argument.

Then there's some general overview text.

Then we document arguments that are passed into listeners under an H5 heading called "Arguments". Each argument is documented like argumentType and is bold. That's immediately followed by the description of the argument.