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 at [enter website here]. http://daringfireball.net/projects/markdown/

APIDocs This has roots in the JavaDocs 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. [reference a JavaDocs site]

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.

• file structure
• .md file corresponds to the .js file
• APIDocs and code example