1 | # Firedoc Syntax Guide
|
2 |
|
3 | Firedoc is compatible with all YUIDoc tags (http://yui.github.io/yuidoc/syntax/).
|
4 | If you find some tags not working with Firedoc feel free to [submit an issue](https://github.com/fireball-x/firedoc/issues).
|
5 |
|
6 | > Firedoc is based on YUIDoc so it only does process comments, not actual code.
|
7 |
|
8 | Firedoc has the following enhanced features:
|
9 |
|
10 | - [Members for Module](#members-for-module)
|
11 | - [Callback Function](#callback-function)
|
12 | - [Multi-language Description](#multi-language-description)
|
13 | - [Single-line Property/Parameter Declaration](#single-line-propertyparameter-declaration)
|
14 | - [Enum](#enum)
|
15 | - [Example Link to File](#example-link-to-file)
|
16 | - [Detailed Properties of Object Parameter](#detailed-properties-of-object-parameter)
|
17 |
|
18 | ## Members for Module
|
19 |
|
20 | In both JSDoc and YUIDoc, properties and methods can only exists under `@class`. Firedoc supports direct member of modules.
|
21 | You can declare members under module like this:
|
22 | ```js
|
23 | /**
|
24 | * @module FireDoc
|
25 | */
|
26 | /**
|
27 | * Prop description
|
28 | * @property test2
|
29 | * @type {String}
|
30 | */
|
31 | var test2;
|
32 | ```
|
33 |
|
34 | The property `test2` will be listed under `FireDoc` module page. No need to create psuedo classes just for hoding global methods and properties.
|
35 |
|
36 | ## Callback Function
|
37 |
|
38 | Firedoc added `@callback` tag for declaring callback function signature that you can reuse in many methods.
|
39 |
|
40 | ```js
|
41 | /**
|
42 | * @callback ExampleCallback
|
43 | * @param {String} html The HTML to write module view.
|
44 | * @param {Object} view The View Data.
|
45 | */
|
46 | /**
|
47 | * Generates the module files undert "out"/modules/
|
48 | * @method test2
|
49 | * @param {ExampleCallback} cb The callback to execute after it's completed
|
50 | */
|
51 | /**
|
52 | * Generates the module files undert "out"/modules/
|
53 | * @method test3
|
54 | * @param {String} id
|
55 | * @param {ExampleCallback} cb The callback to execute after it's completed
|
56 | */
|
57 | ```
|
58 | 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) .
|
59 |
|
60 | ## Multi-language Description
|
61 |
|
62 | 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.
|
63 |
|
64 | You can use two patterns for inserting language tags:
|
65 |
|
66 | ### Multilines
|
67 |
|
68 | ```js
|
69 | /**
|
70 | * !#en
|
71 | * English class description
|
72 | * !#zh
|
73 | * 中文类型描述
|
74 | * @class FLogic
|
75 | */
|
76 | ```
|
77 |
|
78 | ### Inline
|
79 |
|
80 | ```js
|
81 | /**
|
82 | * !#en English class description !#zh 中文类型描述
|
83 | * @class FLogic
|
84 | */
|
85 | ```
|
86 |
|
87 | ## Single-line Property/Parameter Declaration
|
88 |
|
89 | Same as JSDoc syntax:
|
90 | ```js
|
91 | /**
|
92 | * @property {Vec2} position - The local position in its parent's coordinate system
|
93 | */
|
94 | ```
|
95 |
|
96 | ## Enum
|
97 |
|
98 | Use `@enum` with `@property` to document enum definitions.
|
99 |
|
100 | ```js
|
101 | /**
|
102 | * Enum description
|
103 | * @enum NumberableBool
|
104 | */
|
105 | var NumberableBool = {
|
106 | /**
|
107 | * @property {number} TRUE - stands for true
|
108 | */
|
109 | TRUE: 1,
|
110 | /**
|
111 | * @property {number} FALSE - stands for false
|
112 | */
|
113 | FALSE: -1,
|
114 | };
|
115 | ```
|
116 |
|
117 | You can write all `@property` in the same comment block as the enum declaration.
|
118 |
|
119 | ## Example Link to File
|
120 |
|
121 | Use `@example` with `@link` to display code in a file as example.
|
122 |
|
123 | ```js
|
124 | /**
|
125 | * @method example
|
126 | * @example {@link path/to/example.js }
|
127 | */
|
128 | ```
|
129 |
|
130 | The path `path/to/example.js` is based at your execution path (or cwd).
|
131 |
|
132 | ## Detailed Properties of Object Parameter
|
133 |
|
134 | If you want to detail the properties of a object parameter for a method, use the following pattern:
|
135 |
|
136 | ```js
|
137 | /**
|
138 | * @method star
|
139 | * @param {String} command The command to run
|
140 | * @param {Array} args List of string arguments
|
141 | * @param {Object} options
|
142 | * @param {String} options.cwd
|
143 | * @param {Object} options.env
|
144 | * @param {Array|String} options.stdio
|
145 | * @param {Array} options.customFds
|
146 | */
|
147 | ```
|