Jetpack/SDK/Writing Documentation

Writing Documentation for the Add-on SDK

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:

• That the documentation is written in Markdown syntax
• That the API elements are described in APIDoc syntax
• That there are corresponding .js/.md files in the lib/docs directories (e.g. tabs.js/tabs.md)

APIDoc Syntax

"APIDoc" is a simple markup syntax we've defined for documenting the component parts of an API.

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 widely-used syntax such as JSDoc in the future.

A good way to understand the syntax is to look at the existing module documentation, which can be found in your SDK installation, under packages/addon-kit/docs/.

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

APIDoc defines the following types:

• function
• class
• constructor
• method
• property
• event

The next section describes the parts of the syntax that are common across all types, then we'll explain syntax specific to the different type in the subsequent sections.

Basic Usage

In APIDoc each API element is enclosed inside <api></api> tags.

• The opening tag contains a "name" attribute which is the name of the element.

• The line immediately following the opening tag is the name of the type, preceded by "@".

• The lines after this contain the description. You can include Markdown in the description.

For example:

<api name="postMessage">

@function
Use this function to send a message
to any [content scripts](/link/to/doc.html).

</api>

<api name="open">

@event
This event is generated when the
corresponding `tab` object is opened.

</api>

Nesting

Certain elements are allowed to contain others:

• class elements may contain constructor, method, property, and event elements.
• property elements may contain method, property, and event elements.

So an object called panel that emits an event called show would be documented like this:

<api name="panel">

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

If the element isn't nested like this, that means it's defined at module scope.

constructor, function, method

The syntax for constructor, function, and method types is identical: the only difference is that:

• constructor types are always nested inside a class type and must not return a value
• method types are always nested inside class or property types
• function types are always defined at module scope

Parameters

You list parameters after the function's description using a line which:

• starts with the "@param" tag
• 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:

<api name="alert">

 @method
 Displays an alert message.

 @param alerttext {string}
 The string to display.

 @param anotherparam {bool}
 Another parameter.

</api>

If the parameter is optional, then the name is enclosed in square brackets:

<api name="alert">

 @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:

<api name="alert">

 @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:

• starts with "@prop"
• 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">
@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

You can specify return values using a line which:

• starts with "@returns"
• is followed by the data type of the return value, enclosed in braces:

<api name="get">

@method
Make a `GET` request.

@returns {Request}
Returns the `Request` object itself.

</api>

class

class types don't have any special syntax, except that you can nest constructor, method, property, or event types inside them:

<api-name="Widget">

@class
Represents a widget object.

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

property

property types indicate the data type of the property, enclosed in braces, immediately following the @property tag:

<api name="label">

@property {string}
  The widget's label.  Read-only.

</api>

You can nest method, property, or event components inside property components.

event

If the code emits events you use the event type 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>