Jetpack/SDK/Writing Documentation

Writing Documentation with the Add-ons Builder SDK

Documentation in the Jetpack SDK is a self-contained system; it is dynamically built based on the files contained within the structure of the SDK. The javascript lives in jetpack-sdk/packages/<package-name>/js the corresponding documentation lives in jetpack-sdk/packages/<package-name>/docs. As long as the prefix for the .js and the .md files is the same, the documentation will be generated and viewable via the "cfx docs" command.

Markdown

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

APIDocs

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.

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:

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

Further examples can be found in the jetpack-core/docs directory.

Submitting changes/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/ [show screenshot of fields]

2. Please CC: sdkdocs@mozilla.com when you submit the bug, so that the review goes to the correct audience. [show screenshot of "CC"]

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.