canmove, Confirmed users
737
edits
Jetpack/SDK/Writing Documentation: Difference between revisions
Jump to navigation
Jump to search
→APIDoc Syntax
| Line 20: | Line 20: | ||
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 then renders them to HTML. | 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 then renders them to HTML. | ||
APIDoc defines the following | APIDoc defines the following types: | ||
* <code>function</code> | * <code>function</code> | ||
| Line 29: | Line 29: | ||
* <code>event</code> | * <code>event</code> | ||
The next section describes the parts of the syntax that are common across all | The next section describes the parts of the syntax that are common across all types, then we'll explain syntax specific to the different type in the subsequent sections. | ||
=== | === Basic Usage === | ||
In APIDoc each API | In APIDoc each API element is enclosed inside <code><api></api></code> tags. | ||
* The opening tag contains a "name" attribute which is the name of the | * The opening tag contains a "name" attribute which is the name of the element. | ||
* The line immediately following the opening tag is the name of the | * The line immediately following the opening tag is the name of the type, preceded by "@". | ||
* The lines | * The lines after this contain the description. You can include Markdown in the description. | ||
For example: | For example: | ||
| Line 59: | Line 59: | ||
</api> | </api> | ||
==== | ==== Nesting ==== | ||
Certain | Certain elements are allowed to contain others: | ||
* <code>class</code> | * <code>class</code> elements may contain <code>constructor</code>, <code>method</code>, <code>property</code>, and <code>event</code> elements. | ||
* <code>property</code> | * <code>property</code> elements may contain <code>method</code>, <code>property</code>, and <code>event</code> elements. | ||
So an object called <code>panel</code> that emits an event called <code>show</code> would be documented like this: | So an object called <code>panel</code> that emits an event called <code>show</code> would be documented like this: | ||
| Line 81: | Line 81: | ||
(The indentation doesn't have any meaning, it just makes things easier to read.) | (The indentation doesn't have any meaning, it just makes things easier to read.) | ||
If the | If the element isn't nested like this, that means it's defined at module scope. | ||
=== <code>constructor</code>, <code>function</code>, <code>method</code> === | === <code>constructor</code>, <code>function</code>, <code>method</code> === | ||
The syntax for <code>constructor</code>, <code>function</code>, and <code>method</code> types is identical: the only difference is that: | The syntax for <code>constructor</code>, <code>function</code>, and <code>method</code> types is identical: the only difference is that: | ||
* <code>constructor</code> | * <code>constructor</code> types are always nested inside a <code>class</code> type and must not return a value | ||
* <code>method</code> | * <code>method</code> types are always nested inside <code>class</code> or <code>property</code> types | ||
* <code>function</code> | * <code>function</code> types are always defined at module scope | ||
==== Parameters ==== | ==== Parameters ==== | ||
| Line 177: | Line 177: | ||
=== <code>class</code> === | === <code>class</code> === | ||
<code>class</code> | <code>class</code> types don't have any special syntax, except that you can nest <code>constructor</code>, <code>method</code>, <code>property</code>, or <code>event</code> types inside them: | ||
<api-name="Widget"> | <api-name="Widget"> | ||
| Line 209: | Line 209: | ||
=== <code>property</code> === | === <code>property</code> === | ||
<code>property</code> | <code>property</code> types indicate the data type of the property, enclosed in braces, immediately following the @property tag: | ||
<api name="label"> | <api name="label"> | ||
| Line 222: | Line 222: | ||
=== <code>event</code> === | === <code>event</code> === | ||
If the code emits events you use the <code>event</code> | If the code emits events you use the <code>event</code> type 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 line which: | ||
* starts with "@argument" | * starts with "@argument" | ||