GUIDE.md

Firedoc Syntax Guide

Firedoc is compatible with all YUIDoc tags (http://yui.github.io/yuidoc/syntax/). If you find some tags not working with Firedoc feel free to submit an issue.

Firedoc is based on YUIDoc so it only does process comments, not actual code.

Firedoc has the following enhanced features:

• Members for Module
• Callback Function
• Multi-language Description
• Single-line Property/Parameter Declaration
• Enum
• Example Link to File
• Detailed Properties of Object Parameter

Members for Module

In both JSDoc and YUIDoc, properties and methods can only exists under @class. Firedoc supports direct member of modules. You can declare members under module like this:

/**
 * @module FireDoc
 */
/**
 * Prop description
 * @property test2
 * @type {String}
 */
var test2;

The property test2 will be listed under FireDoc module page. No need to create psuedo classes just for hoding global methods and properties.

Callback Function

Firedoc added @callback tag for declaring callback function signature that you can reuse in many methods.

/**
 * @callback ExampleCallback
 * @param {String} html The HTML to write module view.
 * @param {Object} view The View Data.
 */
 /**
 * Generates the module files undert "out"/modules/
 * @method test2
 * @param {ExampleCallback} cb The callback to execute after it's completed
 */
 /**
 * Generates the module files undert "out"/modules/
 * @method test3
 * @param {String} id
 * @param {ExampleCallback} cb The callback to execute after it's completed
 */

In the above example, both method test2 and test3 reuses callback function ExampleCallback (although in real code it perhaps will be an anonymous function, we give it a name only for convenience of commenting callbacks with the same signatures) .

Multi-language Description

Firedoc supports multi-language description for any module, class, method, property, parameter. Use language tag !#en or !#zh to mark the description in a certain language. Then use firedoc source --zh to generate api docs for that language.

You can use two patterns for inserting language tags:

Multilines

/**
 * !#en
 * English class description
 * !#zh
 * 中文类型描述
 * @class FLogic
 */

Inline

/**
 * !#en English class description !#zh 中文类型描述
 * @class FLogic
 */

Single-line Property/Parameter Declaration

Same as JSDoc syntax:

/**
 * @property {Vec2} position - The local position in its parent's coordinate system
 */

You can also put description ahead:

/**
 * The local position in its parent's coordinate system
 * @property {Vec2} position
 */

Enum

Use @enum with @property to document enum definitions.

/**
 * Enum description
 * @enum NumberableBool
 */
var NumberableBool = {
  /**
   * @property {number} TRUE - stands for true
   */
  TRUE: 1,
  /**
   * @property {number} FALSE - stands for false
   */
  FALSE: -1,
};

You can write all @property in the same comment block as the enum declaration.

Examples

Example Link to File

Use @example with @link to display code in a file as example.

/**
* @method example
* @example {@link path/to/example.js }
*/

The path path/to/example.js is based at your execution path (or cwd).

Example File with Sections

To hold multiple examples in one file, you can write your example file like this:

/** @section Food */

var this = 'burger';

this.cook();

/** @section Drink */

var this = 'cola';

And link it to your example with #section notion:

/**
* @method example
* @example {@link path/to/example.js#Food }
*/

This will gives you the following example text:

var this = 'burger';

this.cook();

Auto Backtick Wrap

Example code in a linked file or inline will be automatically wrapped in ````js` backtick. No need to add them yourself.

Example for Class and Modules

Now you can write @example tag in class or module block.

Detailed Properties of Object Parameter

If you want to detail the properties of a object parameter for a method, use the following pattern:

/**
 * @method star
 * @param {String} command The command to run
 * @param {Array} args List of string arguments
 * @param {Object} options
 * @param {String} options.cwd
 * @param {Object} options.env
 * @param {Array|String} options.stdio
 * @param {Array} options.customFds
 */