forked from jsdoc/jsdoc.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathhowto-amd-modules.html
263 lines (249 loc) · 9.9 KB
/
howto-amd-modules.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="description" content="How to add JSDoc comments to AMD and RequireJS modules.">
<title>Use JSDoc: AMD Modules</title>
<link rel="stylesheet" href="styles/usejsdoc.css">
<link rel="stylesheet" href="styles/prettify.css">
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
<script src="scripts/prettify.js"></script>
</head>
<body>
<header>
<a href="./index.html">@use JSDoc</a>
</header>
<article>
<h1>AMD Modules</h1>
<h2>Table of Contents</h2>
<ul>
<li>
<a href="#overview">Overview</a>
</li>
<li>
<a href="#module-identifiers">Module identifiers</a>
</li>
<li>
<a href="#function-that-returns-an-object-literal">Function that returns an object literal</a>
</li>
<li>
<a href="#function-that-returns-another-function">Function that returns another function</a>
</li>
<li>
<a href="#module-declared-in-a-return-statement">Module declared in a return statement</a>
</li>
<li>
<a href="#module-object-passed-to-a-function">Module object passed to a function</a>
</li>
<li>
<a href="#multiple-modules-defined-in-one-file">Multiple modules defined in one file</a>
</li>
<li>
<a href="#related-links">Related Links</a>
</li>
</ul>
<h2 id="overview">Overview</h2>
<p>JSDoc 3 makes it possible to document modules that use the <a href="https://github.com/amdjs/amdjs-api/blob/master/AMD.md">Asynchronous Module Definition
(AMD)
API</a>, which is implemented by libraries such as <a href="http://requirejs.org/">RequireJS</a>. This page explains
how to document an AMD module for JSDoc, based on the coding conventions that your module uses.</p>
<p>If you're documenting CommonJS or Node.js modules, see <a href="howto-commonjs-modules.html">CommonJS Modules</a> for
instructions.</p>
<h2 id="module-identifiers">Module identifiers</h2>
<p>When you document an AMD module, you'll use an <a href="tags-exports.html"><code>@exports</code> tag</a> or
<a href="tags-module.html"><code>@module</code> tag</a> to document the identifier that's passed to the <code>require()</code> function.
For example, if users load the module by calling <code>require('my/shirt', /* callback */)</code>, you'll write
a JSDoc comment that contains the tag <code>@exports my/shirt</code> or <code>@module my/shirt</code>. The examples below
can help you decide which of these tags to use.</p>
<p>If you use the <code>@exports</code> or <code>@module</code> tag without a value, JSDoc will try to guess the correct
module identifier based on the filepath.</p>
<p>When you use a JSDoc <a href="about-namepaths.html">namepath</a> to refer to a module from another JSDoc comment, you must
add the prefix <code>module:</code>. For example, if you want the documentation for the module <code>my/pants</code> to
link to the module <code>my/shirt</code>, you could use the <a href="tags-see.html"><code>@see</code> tag</a> to document <code>my/pants</code> as
follows:</p>
<pre class="prettyprint lang-js"><code>/**
* Pants module.
* @module my/pants
* @see module:my/shirt
*/
</code></pre>
<p>Similarly, the namepath for each member of the module will start with <code>module:</code>, followed by the
module name. For example, if your <code>my/pants</code> module exports a <code>Jeans</code> constructor, and <code>Jeans</code> has
an instance method named <code>hem</code>, the instance method's longname is <code>module:my/pants.Jeans#hem</code>.</p>
<h2 id="function-that-returns-an-object-literal">Function that returns an object literal</h2>
<p>If you define your AMD module as a function that returns an object literal, use the
<a href="tags-exports.html"><code>@exports</code> tag</a> to document the module's name. JSDoc will automatically detect that
the object's properties are members of the module.</p>
<figure>
<figcaption>Function that returns an object literal</figcaption>
<pre class="prettyprint lang-js"><code>define('my/shirt', function() {
/**
* A module representing a shirt.
* @exports my/shirt
*/
var shirt = {
/** The module's `color` property. */
color: 'black',
/**
* Create a new Turtleneck.
* @class
* @param {string} size - The size (`XS`, `S`, `M`, `L`, `XL`, or `XXL`).
*/
Turtleneck: function(size) {
/** The class's `size` property. */
this.size = size;
}
};
return shirt;
});
</code></pre>
</figure>
<h2 id="function-that-returns-another-function">Function that returns another function</h2>
<p>If you define your module as a function that exports another function, such as a constructor, you
can use a standalone comment with a <a href="tags-module.html"><code>@module</code> tag</a> to document the module. You can then
use an <a href="tags-alias.html"><code>@alias</code> tag</a> to tell JSDoc that the function uses the same longname as the
module.</p>
<figure>
<figcaption>Function that returns a constructor</figcaption>
<pre class="prettyprint lang-js"><code>/**
* A module representing a jacket.
* @module my/jacket
*/
define('my/jacket', function() {
/**
* Create a new jacket.
* @class
* @alias module:my/jacket
*/
var Jacket = function() {
// ...
};
/** Zip up the jacket. */
Jacket.prototype.zip = function() {
// ...
};
return Jacket;
});
</code></pre>
</figure>
<h2 id="module-declared-in-a-return-statement">Module declared in a return statement</h2>
<p>If you declare your module object in a function's <code>return</code> statement, you can use a standalone
comment with a <a href="tags-module.html"><code>@module</code> tag</a> to document the module. You can then add an
<a href="tags-alias.html"><code>@alias</code> tag</a> to tell JSDoc that the module object has the same longname as the module.</p>
<figure>
<figcaption>Module declared in a return statement</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Module representing a shirt.
* @module my/shirt
*/
define('my/shirt', function() {
// Do setup work here.
return /** @alias module:my/shirt */ {
/** Color. */
color: 'black',
/** Size. */
size: 'unisize'
};
});
</code></pre>
</figure>
<h2 id="module-object-passed-to-a-function">Module object passed to a function</h2>
<p>If the module object is passed into the function that defines your module, you can document the
module by adding an <a href="tags-exports.html"><code>@exports</code> tag</a> to the function parameter. This pattern is
supported in JSDoc 3.3.0 and later.</p>
<figure>
<figcaption>Module object passed to a function</figcaption>
<pre class="prettyprint lang-js"><code>define('my/jacket', function(
/**
* Utility functions for jackets.
* @exports my/jacket
*/
module) {
/**
* Zip up a jacket.
* @param {Jacket} jacket - The jacket to zip up.
*/
module.zip = function(jacket) {
// ...
};
});
</code></pre>
</figure>
<h2 id="multiple-modules-defined-in-one-file">Multiple modules defined in one file</h2>
<p>If you define more than one AMD module in a single JavaScript file, use the
<a href="tags-exports.html"><code>@exports</code> tag</a> to document each module object.</p>
<figure>
<figcaption>Multiple AMD modules defined in one file</figcaption>
<pre class="prettyprint lang-js"><code>// one module
define('html/utils', function() {
/**
* Utility functions to ease working with DOM elements.
* @exports html/utils
*/
var utils = {
/**
* Get the value of a property on an element.
* @param {HTMLElement} element - The element.
* @param {string} propertyName - The name of the property.
* @return {*} The value of the property.
*/
getStyleProperty: function(element, propertyName) { }
};
/**
* Determine if an element is in the document head.
* @param {HTMLElement} element - The element.
* @return {boolean} Set to `true` if the element is in the document head,
* `false` otherwise.
*/
utils.isInHead = function(element) { }
return utils;
}
);
// another module
define('tag', function() {
/** @exports tag */
var tag = {
/**
* Create a new Tag.
* @class
* @param {string} tagName - The name of the tag.
*/
Tag: function(tagName) {
// ...
}
};
return tag;
});
</code></pre>
</figure>
<h2 id="related-links">Related Links</h2>
<ul>
<li>
<a href="about-namepaths.html">Using namepaths with JSDoc 3</a>
</li>
<li>
<a href="tags-exports.html">@exports</a>
</li>
<li>
<a href="tags-module.html">@module</a>
</li>
</ul>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" /></a>
<br>
Copyright © 2011-2017 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the
JSDoc 3 documentation project.
<br>
This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is
licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
</footer>
<script type="text/javascript">
prettyPrint();
</script>
</body>
</html>