Jetpack/SDK/Writing Documentation: Difference between revisions

Jetpack/SDK/Writing Documentation (view source)

Revision as of 19:41, 5 December 2013

2,628 bytes added , 5 December 2013

no edit summary

Wbamberg

canmove, Confirmed users

737

edits

@@ Line 71: / Line 71: @@
 * [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.
+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
+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).
-The title is the name of the constructor including any parameters: PageMod(options). That's followed
+==== 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
+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.
+==== 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(parameters)
+* Overview text
+* [H5]Arguments
+* [STRONG]argumentType
+* 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.