Jetpack/SDK/Writing Documentation: Difference between revisions

From MozillaWiki
< Jetpack‎ | SDK
Jump to navigation Jump to search
(Created page with "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 s...")
 
No edit summary
 
(62 intermediate revisions by 2 users not shown)
Line 1: Line 1:
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.
== Documenting SDK modules in MDN ==


Markdown
Each module in the SDK is documented in a single "API reference" page on MDN.
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
=== Creating a new API reference page ===
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
SDK modules are divided into two sorts: high-level and low-level.


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


<api name="activeTab">
* 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".
@property {object}


The currently active tab.  This property can be set to a `tab` object, which
=== API reference page overall structure ===
will focus that tab's parent window and bring the tab to the foreground.
</api>


**Example**
The high-level page organization is like this:


    // get
* Module Stability
    var tabs = require("tabs");
* SEO Summary
    console.log("title of active tab is " + tabs.activeTab.title);
* [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


    // set
==== Module stability ====
    tabs.activeTab = anotherTab;
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].


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


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:
* 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


* APIDocs formatted API reference with a human-readable description
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].
* A short code sample of using the API in context


Further examples can be found in the jetpack-core/docs directory.
==== 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/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/
==== Classes ====
[show screenshot of fields]
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. [show screenshot of "CC"]
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".


==== Constructors ====


Writing Docs For Your Own Modules
Constructors are documented like this:


As you continue developing with the Add-ons Builder SDK, you may want to include documentation with your own modules.
* [H4 class="addon-sdk-api-name"][CODE] Name(parameters)
* Overview text
** [H5]Parameters
** [STRONG]parameterName : parameterType
** Parameter description
**[TABLE]mandatory options
**[TABLE]optional options


* file structure
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).
* .md file corresponds to the .js file
 
* APIDocs and code example
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.

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"