Jetpack/SDK/Writing Documentation: Difference between revisions

From MozillaWiki
< Jetpack‎ | SDK
Jump to navigation Jump to search
No edit summary
 
(46 intermediate revisions by the same user not shown)
Line 1: Line 1:


== Writing Documentation for the Add-ons Builder 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 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.
=== Creating a new API reference page ===


SDK modules are divided into two sorts: high-level and low-level.


=== On Markdown ===
* 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 format for the human-readable documentation for the Jetpack SDK is Markdown. More information about Markdown can be found [http://daringfireball.net/projects/markdown/ here].


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


=== On APIDoc Syntax ===
=== API reference page overall structure ===
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 to provide a way to give a framework for documenting the API in a human-readable format. Please see an overview of JavaDoc format on [http://en.wikipedia.org/wiki/Javadoc wikipedia here].


An example of this syntax in action can be found below.
The high-level page organization is like this:


== A Short, Well Documented Example ==
* 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


    Properties
==== 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 [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].
   
    &lt;api name="activeTab"&gt;
    @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.
    &lt;/api&gt;
   
    **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 example is directly from the tabs.md file. This and all API documentation should have 2 major parts:  
==== 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:


* An APIDoc formatted API reference with a human-readable description
* it appears as the page summary in results from search engines
* A short code sample using the API in context
* it might appear under a link to the page in automatically-generated listings of API reference pages


More examples can be found in the .md files located in the jetpack-core/docs directory. The APIDoc format is robust and being able to immediately view your changes in the documentation engine ("cfx docs") should make updating and authoring API docs relatively straightforward.
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].


Additionally, questions can be directed to the [http://groups.google.com/group/mozilla-labs-jetpack/topics?pli=1 Google Group for Jetpack].
==== 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.


== Submitting Changes and Updates to jetpack-core Documentation ==
==== 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.


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.  
If a module doesn't have any objects of a given category (for example, no module-level events) then that category is omitted.


1. File a bug on https://bugzilla.mozilla.org/ [http://img.skitch.com/20100818-btg1nkr92snxhp7jay8t3996se.jpg See important bugzilla fields to note].
==== 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.


2. Please CC: sdkdocs@mozilla.com when you submit the bug, so that the review goes to the correct audience. [http://img.skitch.com/20100818-bm8e9ghqcpe6c1j91j73bkx7ww.jpg Verify CC to sdkdocs].
Each section will have three H3 subsections: Methods, Properties, Events. Each actual object under there is an H4.


3. Attach your patch to the bug so that it can be reviewed quickly.  
If a class doesn't have any objects of a given category (for example, no properties) then that category is omitted.


4. Iterate as necessary.
=== Documenting API elements ===


5. When the change is approved, it will be submitted to the trunk by an appropriate engineer.
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".


== Writing Docs For Your Own Modules ==
==== Constructors ====


As you continue developing with the Add-ons Builder SDK, you may want to include documentation with your own modules.
Constructors are documented like this:


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.
* [H4 class="addon-sdk-api-name"][CODE] Name(parameters)
* Overview text
** [H5]Parameters
** [STRONG]parameterName : parameterType
** Parameter description
**[TABLE]mandatory options
**[TABLE]optional options


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.
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).
[http://img.skitch.com/20100818-raumdbfmwytkf9qd26sg251a82.jpg 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.
Then there's some general overview text.


The custom documentation should be in Markdown format, and for the stake of standards, should have the following:
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.
* API definition in the APIDoc format as indicated above
* Some small example to illustrate the use of the code in context


Questions and comments can be directed to the [http://groups.google.com/group/mozilla-labs-jetpack/topics?pli=1 google groups for Jetpack].
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.

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"