Jetpack/SDK/Writing Documentation: Difference between revisions

From MozillaWiki
< Jetpack‎ | SDK
Jump to navigation Jump to search
No edit summary
No edit summary
 
(16 intermediate revisions by the same user not shown)
Line 1: Line 1:
__NOTOC__


== Writing Documentation for the Add-on SDK ==
== Documenting SDK modules in MDN ==
Documentation in the Add-on SDK is a self-contained system within the SDK itself. All of the documentation is generated on the fly from Markdown files located in the directory structure. SDK documentation is viewable either as source (at any time) or as a web page after the SDK has been activated and the "cfx docs" command has been run from the command line.


The "cfx docs" command launches a small web server in order to render the documentation in a browser. It relies on three things:
Each module in the SDK is documented in a single "API reference" page on MDN.
* That the documentation is written in [http://daringfireball.net/projects/markdown/ Markdown syntax]
* That the API components are described in [https://wiki.mozilla.org/Jetpack/SDK/Writing_Documentation#APIDoc_Syntax APIDoc] syntax
* That there are corresponding .js/.md files in the lib/docs directories (e.g. tabs.js/tabs.md)


== APIDoc Syntax ==
=== Creating a new API reference page ===


"APIDoc" is a simple markup syntax we've defined for documenting the component parts of an API.
SDK modules are divided into two sorts: high-level and low-level.


The main benefit of using a defined syntax is that we can ensure that all APIs are consistently documented. Having said that, we'd like to move to a more standard syntax in the future.
* 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".


A good way to understand the syntax is to look at the existing module documentation, which can be found in your SDK installation, under <code>packages/addon-kit/docs/</code>.
* 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".


In APIDoc each component of an API - functions, constructors, properties, and so on - is enclosed in a pair of <code><api></api></code> tags. These are recognized by the documentation system, which parses them into a JSON structure and then renders them to HTML.
=== API reference page overall structure ===


APIDoc defines the following component types:
The high-level page organization is like this:


* <code>function</code>
* Module Stability
* <code>class</code>
* SEO Summary
* <code>constructor</code>
* [H2] Usage
* <code>method</code>
* [H2] Globals
* <code>property</code>
** [H3] Constructors
* <code>event</code>
** [H3] Functions
** [H3] Properties
** [H3] Events
* [H2] SomeClassName
** [H3] Methods
** [H3] Properties
** [H3] Events
* [H2] SomeOtherClassName
** [H3] Methods
** [H3] Properties
** [H3] Events


The next section describes the parts of the syntax that are common across all component types, then we'll explain component-type-specific syntax in the subsequent sections.
==== 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].


=== Common Component Syntax ===
==== 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:


In APIDoc each API component is enclosed inside <code><api></api></code> tags.
* 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


* The opening tag contains a "name" attribute which is the name of the component.
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].


* The line immediately following the opening tag is the name of the component type, preceded by "@".
==== 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.


* The lines following the component-type line contain the description for the component. You can include Markdown in the description.
==== 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.


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


<api name="postMessage">
==== 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.
@function
Use this function to send a message
to any [content scripts](/link/to/doc.html).
</api>


<api name="open">
Each section will have three H3 subsections: Methods, Properties, Events. Each actual object under there is an H4.
@event
This event is generated when the
corresponding `tab` object is opened.
</api>


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


Certain components are allowed to contain other components:
=== Documenting API elements ===


* <code>class</code> components may contain <code>constructor</code>, <code>method</code>, <code>property</code>, and <code>event</code> components.
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".
* <code>property</code> components may contain <code>method</code>, <code>property</code>, and <code>event</code> components.


So an object called <code>panel</code> that emits an event called <code>show</code> would be documented like this:
==== Constructors ====


<api name="panel">
Constructors are documented like this:
@class
The panel class.
    <api name="show">
    @event
    This event is emitted when the panel is shown.
    </api>
</api>


(The indentation doesn't have any meaning, it just makes things easier to read.)
* [H4 class="addon-sdk-api-name"][CODE] Name(parameters)
* Overview text
** [H5]Parameters
** [STRONG]parameterName : parameterType
** Parameter description
**[TABLE]mandatory options
**[TABLE]optional options


If the component isn't nested like this, that means it's defined at module scope.
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).


=== <code>constructor</code>, <code>function</code>, <code>method</code> ===
Then there's some general overview text.


The syntax for <code>constructor</code>, <code>function</code>, and <code>method</code> types is identical: the only difference is that:
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.
* <code>constructor</code> components are always nested inside a <code>class</code> component and must not return a value
* <code>method</code> components are always nested inside <code>class</code> or <code>property</code> components
* <code>function</code> components are always defined at module scope


==== Parameters ====
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


You list parameters after the function's description using a line which:
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).


* starts with the "@param" tag
==== Functions ====
* is followed, on the same line, by the name of the parameter and its data type. The data type is enclosed in braces.


Subsequent lines can describe the parameter:
Functions are documented like this:


<api name="alert">
*[H4 class="addon-sdk-api-name"][CODE] Name(parameters)
*Overview text
  @method
**[H5]Parameters
  Displays an alert message.
**[STRONG]parameterName : parameterType
**Parameter description
  @param alerttext {string}
**[TABLE]mandatory options
  The string to display.
**[TABLE]optional options
**[H5]Returns
  @param anotherparam {bool}
**[STRONG]returnsType : [/STRONG]Return value description
  Another parameter.
</api>


If the parameter is optional, then the name is enclosed in square brackets:
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).


<api name="alert">
Then there's some general overview text.
  @method
  Displays an alert message.
  @param [alerttext] {string}
  The string to display.
</api>


If the parameter has a default value, then the name is followed by "=" and then the default value:
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.


<api name="alert">
If the function has an options object as a parameter then the options are documented in up to 2 tables:
  @method
  Displays an alert message.
  @param [anotherparam=false] {bool}
  Some boolean or other.
 
</api>


Parameters can contain properties of their own. In this case the properties are listed after the parameter description, using a line which:
* the first table lists mandatory options
* the second table lists optional options


* starts with "@prop"
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.
* is followed by the name of the property, enclosed in square brackets if the property is optional
* is followed by the data type, enclosed in braces


<api name="open">
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.
@function
Open a new window.
@param options {object}
An object containing configurable options for how this window will be opened,
as well as a callback for being notified when the window has fully opened.
  @prop url {string}
  String URL to be opened in the new window.
 
  @prop [onOpen] {function}
  A callback function that is called when the window has opened.
</api>


==== Return values ====
==== Properties ====
Properties are documented like this:


You can specify return values using a line which:
* [H4 class="addon-sdk-api-name"][CODE] Name
* Description
** [H5]Parameters
** [STRONG]parameterName : parameterType
** Parameter description


* starts with "@returns"
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".
* is followed by the data type of the return value, enclosed in braces:


<api name="get">
Then there's a description.
@method
Make a `GET` request.
@returns {Request}
Returns the `Request` object itself.
</api>


=== <code>class</code> ===
==== Events ====


<code>class</code> components don't have any special syntax, except that you can nest <code>constructor</code>, <code>method</code>, <code>property</code>, or <code>event</code> components inside them:
Functions are documented like this:


<api-name="Widget">
* [H4 class="addon-sdk-api-name"][CODE] Name
* Overview text
@class
** [H5]Arguments
Represents a widget object.
** [STRONG]argumentType : [/STRONG] Argument description
    <api name="Widget">
    @constructor
      Creates a new widget.  The widget is immediately added to the add-on bar.
    </api>
    <api name="destroy">
    @method
      Removes the widget from the add-on bar.
    </api>
    <api name="width">
    @property {number}
      The widget's width in pixels.  Setting it updates the widget's appearance
      immediately.
    </api>
    <api name="mouseover">
    @event
    This event is emitted when the user moves the mouse over the widget.
    </api>
</api>


=== <code>property</code> ===
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.


<code>property</code> components indicate the data type of the property, enclosed in braces, immediately following the @property tag:
Then there's some general overview text.


<api name="label">
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.
@property {string}
  The widget's label.  Read-only.
</api>
 
You can nest <code>method</code>, <code>property</code>, or <code>event</code> components inside <code>property</code> components.
 
=== <code>event</code> ===
 
If the code emits events you use the <code>event</code> component to document them. The only extra bit of syntax events need is to define the arguments that will be passed into any listener functions, and this is done using a line which:
 
* starts with "@argument"
* is followed by the data type of the argument in braces:
 
<api name="complete">
@event
The `Request` object emits this event when the request has completed and a
response has been received.
@argument {Response}
Listener functions are passed the response to the request as a `Response` object.
</api>

Latest revision as of 22:47, 17 December 2013

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

Retrieved from "https://wiki.allizom.org/index.php?title=Jetpack/SDK/Writing_Documentation&oldid=799246"