MozillaWiki

Jetpack/SDK/Writing Documentation: Difference between revisions

Page Discussion

Jetpack/SDK/Writing Documentation (view source)

Revision as of 22:22, 10 June 2011

1,966 bytes added ,  10 June 2011
no edit summary
No edit summary
Line 1: Line 1:
__NOTOC__


== Writing Documentation for the Add-ons Builder SDK ==
== Writing Documentation for the Add-ons Builder SDK ==
Line 5: Line 6:


The "cfx docs" command launches a small web server in order to render the documentation for human consumption. It relies on three things:
The "cfx docs" command launches a small web server in order to render the documentation for human consumption. It relies on three things:
* That the documentation is written in Markdown syntax
* That the documentation is written in [http://daringfireball.net/projects/markdown/ Markdown syntax]
* That the API component is described in APIDoc 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)
* 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.
== APIDoc Syntax ==


"APIDoc" is a simple markup syntax we've defined for documenting the component parts of an API.


=== On Markdown ===
In APIDoc each component of an API - functions, constructors, properties, and so on - is enclosed in a pair of <code><api></api></code> tags. These are recognized by the documentation system, which parses them into a JSON structure and the renders them to HTML.
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].


The main benefit of using a defined syntax is that we can ensure that all APIs are consistently documented. Having said that, we'd like to move to a more standard syntax in the future.


=== On APIDoc Syntax ===
A good way to understand the syntax is to look at the existing module documentation, which can be found in your SDK installation, under <code>packages/addon-kit/docs/</code>.
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.
=== Component Types ===


== A Short, Well Documented Example ==
APIDoc defines the following component types:
 
* <code>function</code>
* <code>class</code>
* <code>constructor</code>
* <code>method</code>
* <code>property</code>
* <code>event</code>
 
The next section describes the parts of the syntax that are common across all component types, then we'll explain component-type-specific syntax in the subsequent sections.
 
=== Common Component Syntax ===
 
In APIDoc each API component is enclosed inside <code><api></api></code> tags.
 
* The opening tag contains a "name" attribute which is the identifier for the component.
 
* The line immediately following the opening tag is the name of the component type, preceded by "@".
 
* The lines following the component-type line contain the description for the component. You can include Markdown in the description.
 
For example:
 
<api name="postMessage">
@function
Use this function to send a message
to any [content scripts](/link/to/doc.html).
</api>
 
<api name="open">
@event
This event is generated when the
corresponding `tab` object is opened.
</api>
 
==== Component Scope ====
 
Certain components are allowed to contain other components: <code>class</code> and <code>property</code> components may contain <code>constructor</code>, <code>method</code>, <code>property</code>, and <code>event</code> components. So an object called <code>panel</code> that emits a <code>show</code> would be documented like this:
 
<api name="panel">
@class
...
    <api name="show">
    @event
    ...
    </api>
</api>
 
(The indentation doesn't have any meaning, it just makes things easier to read.)
If the component isn't nested like this, that means it's defined at module scope.
 
=== <code>constructor</code>, <code>function</code>, and <code>method</code> Syntax ===
 
The syntax for <code>function</code> and <code>method</code> types is identical: the only difference is that <code>method</code> components are nested inside <code>class</code> or <code>property</code> components, whereas <code>function</code> components aren't. The syntax for <code>constructor</code> is identical, except that it must be nested inside a <code>class</code> component and must not return a value.
 
==== Parameters ====
 
You list parameters after the function's description using the "@param" tag. This is followed, on the same line, by the name of the parameter and its data type. The data type is enclosed in braces. Subsequent lines can describe the parameter:
 
<api name="alert">
  @method
  Displays an alert message.
  @param alerttext {string}
  The string to display.
   
   
  @param anotherparam {bool}
  Another, less useful, parameter.
If the parameter is optional, then the name is enclosed in square brackets:


    Properties
<api name="alert">
  ----------
  @method
   
  Displays an alert message.
    &lt;api name="activeTab"&gt;
   
    @property {object}
  @param [alerttext] {string}
   
  The string to display.
    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:  
If the parameter has a default value, then the name is followed by "=" and then the default value:


* An APIDoc formatted API reference with a human-readable description
<api name="alert">
* A short code sample using the API in context
  @method
  Displays an alert message.
  @param [alerttext] {string}
  The string to display.
  @param [anotherparam=false] {bool}
  Another, less useful, parameter.


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.
Parameters can contain properties of their own. In this case the properties are listed after the parameter description, using a line which:


Additionally, questions can be directed to the [http://groups.google.com/group/mozilla-labs-jetpack/topics?pli=1 Google Group for Jetpack].
* starts with "@prop"
* is followed by the name of the property, enclosed in square brackets if the property is optional
* is followed by the data type, enclosed in braces


== Submitting Changes and Updates to jetpack-core Documentation ==
<api name="open">
@function
Open a new window.
   
   
@param options {object}
An object containing configurable options for how this window will be opened,
as well as a callback for being notified when the window has fully opened.
  @prop url {string}
  String URL to be opened in the new window.
 
  @prop [onOpen] {function}
  A callback function that is called when the window has opened.


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.
==== Return values ====


1. File a bug on https://bugzilla.mozilla.org/ [http://img.skitch.com/20100818-btg1nkr92snxhp7jay8t3996se.jpg See important bugzilla fields to note].
You can specify return values using the "@returns" tag. This is followed, on the same line, by the data type of the return value, enclosed in braces:


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].
<api name="get">
@method
Make a `GET` request.
@returns {Request}
</api>


3. Attach your patch to the bug so that it can be reviewed quickly.
=== <code>class</code> Syntax ===


4. Iterate as necessary.  
<code>class</code> components don't have any special syntax, except that you can nest <code>constructor</code>, <code>method</code>, <code>property</code>, or <code>event</code> components inside them.


5. When the change is approved, it will be submitted to the trunk by an appropriate engineer.
=== <code>property</code> Syntax ===


== Writing Docs For Your Own Modules ==
<code>property</code> components indicate the data type of the property, enclosed in braces, immediately following the @property tag:


As you continue developing with the Add-ons Builder SDK, you may want to include documentation with your own modules.
<api name="label">
@property {string}
  The widget's label.  Read-only.
</api>


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.
You can nest <code>method</code>, <code>property</code>, or <code>event</code> components inside <code>property</code> components.


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.
=== <code>event</code> components ===
[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.
If the code emits events you use the <code>event</code> component to document them. The only extra bit of syntax events need is to define the arguments that will be passed into any listener functions, and this is done using a "@argument" tag, followed by the data type of the argument in braces:


The custom documentation should be in Markdown format, and for the stake of standards, should have the following:
<api name="complete">
* API definition in the APIDoc format as indicated above
@event
* Some small example to illustrate the use of the code in context
The `Request` object emits this event when the request has completed and a
response has been received.


Questions and comments can be directed to the [http://groups.google.com/group/mozilla-labs-jetpack/topics?pli=1 google groups for Jetpack].
@argument {Response}
Listener functions are passed the response to the request as a `Response` object.
</api>
Wbamberg
canmove, Confirmed users
737

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/317859"