Jetpack/SDK/Writing Documentation

Writing Documentation for the Add-ons Builder 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)

All documentation for Jetpack(s) should be written using these three tools.

On Markdown

The format for the human-readable documentation for the Jetpack SDK is Markdown. More information about Markdown can be found here.

On APIDoc Syntax

This has roots in the JavaDoc format for documenting APIs within the structure of the Java code itself. The idea was to make it functionally similar to document APIs within the code as well as provide a way to give a framework for documenting the API in a human-readable format. An overview of JavaDoc format on wikipedia.

More details on this syntax can be found in the example below.

A Short, Well Documented Example

   Properties
  ----------
   
   <api name="activeTab">
    @property {object}
   
    The currently active tab.  This property can be set to a `tab` 
    object, which will focus that tab's parent window and bring the 
    tab to the foreground.
   </api>
   
   **Example**
   
     // get
    var tabs = require("tabs");
    console.log("title of active tab is " + tabs.activeTab.title);
   
    // set
   tabs.activeTab = anotherTab;
   

This is a good example of a well documented API within the Jetpack SDK. This is directly from the tabs.md API document. It has 2 major parts:

• APIDoc formatted API reference with a human-readable description
• A short code sample of using the API in context

More complex examples can be found in the .md files located in the jetpack-core/docs directory. The APIDoc format is reasonably robust and the tight feedback loop of being able to immediately view your changes in the documentation engine ("cfx docs") should make updating and authoring API docs relatively straightforward.

Additionally, questions can be directed to the Google Group for Jetpack.

Submitting Changes and Updates to jetpack-core Documentation

Found something that we're missing? Bugs? Additions? In order to contribute to the jetpack-core docs, please follow the following process to get your changes submitted successfully.

1. File a bug on https://bugzilla.mozilla.org/ See important bugzilla fields to note.

2. Please CC: sdkdocs@mozilla.com when you submit the bug, so that the review goes to the correct audience. Verify CC to sdkdocs.

3. Attach your patch to the bug so that it can be reviewed quickly.

4. Iterate as necessary.

5. When the change is approved, it will be submitted to the trunk by an appropriate engineer.

Writing Docs For Your Own Modules

As you continue developing with the Add-ons Builder SDK, you may want to include documentation with your own modules.

Documentation for core Jetpack modules and custom libraries can be found when you run "cfx docs" after activating the source. "cfx docs" launches a browser window where the documentation is viewable.

In the jetpack-sdk/packages/<your module> directory, you can include a file called README.md. This file may contain some high level-level information about the package. The README.md and package.json files will generate a well formatted page that contains an overview of the package. Documentation Example

Below the module on the left column is a list of the component modules, as built from the .js files in the jetpack-sdk/package/<your module>/lib directory. When you click on the name of the *lib*, the corresponding .md file in the docs directory is opened in the right column.

The custom documentation should be in Markdown format, and for the stake of standards, should have the following:

• API definition in the APIDocs format as indicated above
• Some small example to illustrate the use of the code in context

Questions and comments can be directed to the google groups for Jetpack.