-
Notifications
You must be signed in to change notification settings - Fork 105
/
Copy pathhowto-commonjs-modules.html
364 lines (347 loc) · 14.3 KB
/
howto-commonjs-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
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
<!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 CommonJS and Node.js modules.">
<title>Use JSDoc: CommonJS 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>CommonJS 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="#properties-of-the-exports-object">Properties of the 'exports' object</a>
</li>
<li>
<a href="#values-assigned-to-local-variables">Values assigned to local variables</a>
</li>
<li>
<a href="#values-assigned-to-moduleexports">Values assigned to 'module.exports'</a>
<ul>
<li>
<a href="#object-literal-assigned-to-moduleexports">Object literal assigned to 'module.exports'</a>
</li>
<li>
<a href="#function-assigned-to-moduleexports">Function assigned to 'module.exports'</a>
</li>
<li>
<a href="#string-number-or-boolean-assigned-to-moduleexports">String, number, or boolean assigned to 'module.exports'</a>
</li>
</ul>
</li>
<li>
<a href="#values-assigned-to-moduleexports-and-local-variables">Values assigned to 'module.exports' and local variables</a>
</li>
<li>
<a href="#properties-added-to-this">Properties added to 'this'</a>
</li>
<li>
<a href="#related-links">Related Links</a>
</li>
</ul>
<h2 id="overview">Overview</h2>
<p>To help you document <a href="http://wiki.commonjs.org/wiki/Modules/1.1">CommonJS modules</a>, JSDoc 3 understands many of the
conventions used in the CommonJS specification (for example, adding properties to the <code>exports</code>
object). In addition, JSDoc recognizes the conventions of <a href="http://nodejs.org/api/modules.html">Node.js modules</a>, which
extend the CommonJS standard (for example, assigning a value to <code>module.exports</code>). Depending on the
coding conventions you follow, you may need to provide some additional tags to help JSDoc understand
your code.</p>
<p>This page explains how to document CommonJS and Node.js modules that use several different coding
conventions. If you're documenting Asynchronous Module Definition (AMD) modules (also
known as "RequireJS modules"), see <a href="howto-amd-modules.html">AMD Modules</a>.</p>
<h2 id="module-identifiers">Module identifiers</h2>
<p>In most cases, your CommonJS or Node.js module should include a standalone JSDoc comment that
contains a <a href="tags-module.html"><code>@module</code> tag</a>. The <code>@module</code> tag's value should be the module identifier
that's passed to the <code>require()</code> function. For example, if users load the module by calling
<code>require('my/shirt')</code>, your JSDoc comment would contain the tag <code>@module my/shirt</code>.</p>
<p>If you use the <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="properties-of-the-exports-object">Properties of the 'exports' object</h2>
<p>It's easiest to document symbols that are directly assigned to a property of the <code>exports</code> object.
JSDoc will automatically recognize that the module exports these symbols.</p>
<p>In the following example, the <code>my/shirt</code> module exports the methods <code>button</code> and <code>unbutton</code>. JSDoc
will automatically detect that the module exports these methods.</p>
<figure>
<figcaption>Methods added to the exports object</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Shirt module.
* @module my/shirt
*/
/** Button the shirt. */
exports.button = function() {
// ...
};
/** Unbutton the shirt. */
exports.unbutton = function() {
// ...
};
</code></pre>
</figure>
<p><a name="local-vars"></a></p>
<h2 id="values-assigned-to-local-variables">Values assigned to local variables</h2>
<p>In some cases, an exported symbol may be assigned to a local variable before it's added to the
<code>exports</code> object. For example, if your module exports a <code>wash</code> method, and the module itself often
calls the <code>wash</code> method, you might write the module as follows:</p>
<figure>
<figcaption>Method assigned to a local variable and added to the exports object</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Shirt module.
* @module my/shirt
*/
/** Wash the shirt. */
var wash = exports.wash = function() {
// ...
};
</code></pre>
</figure>
<p>In this case, JSDoc will <em>not</em> automatically document <code>wash</code> as an exported method, because the
JSDoc comment appears immediately before the local variable <code>wash</code> rather than <code>exports.wash</code>. One
solution is to add an <a href="tags-alias.html"><code>@alias</code> tag</a> that defines the correct longname for the method. In
this case, the method is a static member of the module <code>my/shirt</code>, so the correct longname is
<code>module:my/shirt.wash</code>:</p>
<figure>
<figcaption>Longname defined in an @alias tag</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Shirt module.
* @module my/shirt
*/
/**
* Wash the shirt.
* @alias module:my/shirt.wash
*/
var wash = exports.wash = function() {
// ...
};
</code></pre>
</figure>
<p>Another solution is to move the method's JSDoc comment so it comes immediately before
<code>exports.wash</code>. This change allows JSDoc to detect that <code>wash</code> is exported by the module <code>my/shirt</code>:</p>
<figure>
<figcaption>JSDoc comment immediately before exports.wash</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Shirt module.
* @module my/shirt
*/
var wash =
/** Wash the shirt. */
exports.wash = function() {
// ...
};
</code></pre>
</figure>
<h2 id="values-assigned-to-moduleexports">Values assigned to 'module.exports'</h2>
<p>In a Node.js module, you can assign a value directly to <code>module.exports</code>. This section explains how
to document different types of values when they are assigned to <code>module.exports</code>.</p>
<h3 id="object-literal-assigned-to-moduleexports">Object literal assigned to 'module.exports'</h3>
<p>If a module assigns an object literal to <code>module.exports</code>. JSDoc automatically recognizes that the
module exports only this value. In addition, JSDoc automatically sets the correct longname for each
property:</p>
<figure>
<figcaption>Object literal assigned to module.exports</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Color mixer.
* @module color/mixer
*/
module.exports = {
/**
* Blend two colors together.
* @param {string} color1 - The first color, in hexadecimal format.
* @param {string} color2 - The second color, in hexadecimal format.
* @return {string} The blended color.
*/
blend: function(color1, color2) {
// ...
},
/**
* Darken a color by the given percentage.
* @param {string} color - The color, in hexadecimal format.
* @param {number} percent - The percentage, ranging from 0 to 100.
* @return {string} The darkened color.
*/
darken: function(color, percent) {
// ..
}
};
</code></pre>
</figure>
<p>You can also use this pattern if you add properties to <code>module.exports</code> outside of the object
literal:</p>
<figure>
<figcaption>Assignment to module.exports followed by property definition</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Color mixer.
* @module color/mixer
*/
module.exports = {
/**
* Blend two colors together.
* @param {string} color1 - The first color, in hexadecimal format.
* @param {string} color2 - The second color, in hexadecimal format.
* @return {string} The blended color.
*/
blend: function(color1, color2) {
// ...
}
};
/**
* Darken a color by the given percentage.
* @param {string} color - The color, in hexadecimal format.
* @param {number} percent - The percentage, ranging from 0 to 100.
* @return {string} The darkened color.
*/
module.exports.darken = function(color, percent) {
// ..
};
</code></pre>
</figure>
<h3 id="function-assigned-to-moduleexports">Function assigned to 'module.exports'</h3>
<p>If you assign a function to <code>module.exports</code>, JSDoc will automatically set the correct longname for
the function:</p>
<figure>
<figcaption>Function assigned to 'module.exports'</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Color mixer.
* @module color/mixer
*/
/**
* Blend two colors together.
* @param {string} color1 - The first color, in hexadecimal format.
* @param {string} color2 - The second color, in hexadecimal format.
* @return {string} The blended color.
*/
module.exports = function(color1, color2) {
// ...
};
</code></pre>
</figure>
<p>The same pattern works for constructor functions:</p>
<figure>
<figcaption>Constructor assigned to 'module.exports'</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Color mixer.
* @module color/mixer
*/
/** Create a color mixer. */
module.exports = function ColorMixer() {
// ...
};
</code></pre>
</figure>
<h3 id="string-number-or-boolean-assigned-to-moduleexports">String, number, or boolean assigned to 'module.exports'</h3>
<p>For value types (strings, numbers, and booleans) assigned to <code>module.exports</code>, you must document the
exported value's type by using the <a href="tags-type.html"><code>@type</code> tag</a> in the same JSDoc comment as the
<code>@module</code> tag:</p>
<figure>
<figcaption>String assigned to module.exports</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Module representing the word of the day.
* @module wotd
* @type {string}
*/
module.exports = 'perniciousness';
</code></pre>
</figure>
<h2 id="values-assigned-to-moduleexports-and-local-variables">Values assigned to 'module.exports' and local variables</h2>
<p>If your module exports symbols that are not directly assigned to <code>module.exports</code>, you can use the
<a href="tags-exports.html"><code>@exports</code> tag</a> in place of the <code>@module</code> tag. The <code>@exports</code> tag tells JSDoc that a
symbol represents the value exported by a module.</p>
<figure>
<figcaption>Object literal assigned to a local variable and module.exports</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Color mixer.
* @exports color/mixer
*/
var mixer = module.exports = {
/**
* Blend two colors together.
* @param {string} color1 - The first color, in hexadecimal format.
* @param {string} color2 - The second color, in hexadecimal format.
* @return {string} The blended color.
*/
blend: function(color1, color2) {
// ...
}
};
</code></pre>
</figure>
<h2 id="properties-added-to-this">Properties added to 'this'</h2>
<p>When a module adds a property to its <code>this</code> object, JSDoc 3 automatically recognizes that the new
property is exported by the module:</p>
<figure>
<figcaption>Properties added to a module's 'this' object</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Module for bookshelf-related utilities.
* @module bookshelf
*/
/**
* Create a new Book.
* @class
* @param {string} title - The title of the book.
*/
this.Book = function(title) {
/** The title of the book. */
this.title = title;
}
</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-2019 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>
<p>
<a href="https://github.com/jsdoc3/jsdoc" class="github-ribbon">Fork me on GitHub</a>
</p>
<script type="text/javascript">
prettyPrint();
</script>
</body>
</html>