Writing Documentation for the Add-on SDK
Documentation in the Jetpack SDK is a self-contained system within the SDK itself. All of the documentation is generated on the fly, via actual 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 for human consumption. It relies on three things:
- That the documentation is written in Markdown syntax
- That the API component is 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.
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.
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.
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/.
Component Types
APIDoc defines the following component types:
functionclassconstructormethodpropertyevent
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.
Common Component Syntax
In APIDoc each API component is enclosed inside <api></api> tags.
- The opening tag contains a "name" attribute which is the name of the component.
- The line immediately following the opening tag is the name of the component type, preceded by "@".
- The lines following the component-type line contain the description for the component. 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>
Component Scope
Certain components are allowed to contain other components: class and property components may contain constructor, method, property, and event components. So an object called panel that emits an event called show would be documented like this:
<api name="panel"> @class ... <api name="show"> @event ... </api> </api>
(The indentation doesn't have any meaning, it just makes things easier to read.) If the component isn't nested like this, that means it's defined at module scope.
constructor, function, and method Syntax
The syntax for function and method types is identical: the only difference is that method components are nested inside class or property components, whereas function components aren't.
The syntax for constructor is identical, except that it must be nested inside a class component and must not return a value.
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 the "@returns" tag. This is followed, on the same line, by the data type of the return value, enclosed in braces:
<api name="get">
@method
Make a `GET` request.
@returns {Request}
</api>
class Syntax
class components don't have any special syntax, except that you can nest constructor, method, property, or event components inside them.
property Syntax
property components 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 components
If the code emits events you use the event 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 "@argument" tag, 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>