Jetpack/SDK/Writing Documentation: Difference between revisions

From MozillaWiki
< Jetpack‎ | SDK
Jump to navigation Jump to search
No edit summary
 
(36 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 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:
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 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 ==
=== 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.


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


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


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>.
=== API reference page overall structure ===


=== Component Types ===
The high-level page organization is like this:


APIDoc defines the following component types:
* 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


* <code>function</code>
==== Module stability ====
* <code>class</code>
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].
* <code>constructor</code>
* <code>method</code>
* <code>property</code>
* <code>event</code>


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


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


In APIDoc each API component is enclosed inside <code><api></api></code> tags.
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 opening tag contains a "name" attribute which is the name of the component.
==== 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 line immediately following the opening tag is the name of the component type, preceded by "@".
==== 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.


* The lines following the component-type line contain the description for the component. You can include Markdown in the description.
If a module doesn't have any objects of a given category (for example, no module-level events) then that category is omitted.


For example:
==== 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.


<api name="postMessage">
Each section will have three H3 subsections: Methods, Properties, Events. Each actual object under there is an H4.
@function
Use this function to send a message
to any [content scripts](/link/to/doc.html).
</api>


<api name="open">
If a class doesn't have any objects of a given category (for example, no properties) then that category is omitted.


@event
=== Documenting API elements ===
This event is generated when the
corresponding `tab` object is opened.
</api>


==== Component Scope ====
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".


Certain components are allowed to contain other components: <code>class</code> and <code>property</code> components may contain <code>constructor</code>, <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
...
    <api name="show">
    @event
    ...
    </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)
If the component isn't nested like this, that means it's defined at module scope.
* Overview text
** [H5]Parameters
** [STRONG]parameterName : parameterType
** Parameter description
**[TABLE]mandatory options
**[TABLE]optional options


=== <code>constructor</code>, <code>function</code>, and <code>method</code> Syntax ===
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).


The syntax for <code>function</code> and <code>method</code> types is identical: the only difference is that <code>method</code> components are nested inside <code>class</code> or <code>property</code> components, whereas <code>function</code> components aren't.
Then there's some general overview text.


The syntax for <code>constructor</code> is identical, except that it must be nested inside a <code>class</code> component and must not return a 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.


==== 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
**[H5]Parameters
**[STRONG]parameterName : parameterType
**Parameter description
**[TABLE]mandatory options
**[TABLE]optional options
**[H5]Returns
**[STRONG]returnsType : [/STRONG]Return value description


  @method
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).
  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:
Then there's some general overview text.


<api name="alert">
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.
  @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:
If the function has an options object as a parameter then the options are documented in up to 2 tables:


<api name="alert">
* the first table lists mandatory options
* the second table lists optional options
  @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:
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.


* starts with "@prop"
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.
* 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">
==== Properties ====
@function
Properties are documented like this:
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 ====
* [H4 class="addon-sdk-api-name"][CODE] Name
* Description
** [H5]Parameters
** [STRONG]parameterName : parameterType
** Parameter description


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


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


=== <code>class</code> Syntax ===
==== 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:


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


<code>property</code> components indicate the data type of the property, enclosed in braces, immediately following the @property tag:
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.


<api name="label">
Then there's some general overview text.


@property {string}
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.
  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> components ===
 
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 "@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>

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"