jsdoc.github.io/howto-commonjs-modules.html at e5f4d9d8e0f5defee7b3bd9a1f0d8d74f24efc86 · jsdoc/jsdoc.github.io · GitHub

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
<!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>CommonJS Modules &ndash; Use JSDoc</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>
  <!--[if lt IE 9]>
            <script src="scripts/html5shiv.min.js"></script>
            <script src="scripts/html5shiv-printshiv.min.js"></script>
        <![endif]-->
</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 &#39;exports&#39; object</a>
      </li>
      <li>
        <a href="#values-assigned-to-local-variables">Values assigned to local variables</a>
      </li>
      <li>
        <a href="#values-assigned-to-module-exports-">Values assigned to &#39;module.exports&#39;</a>
        <ul>
          <li>
            <a href="#object-literal-assigned-to-module-exports-">Object literal assigned to &#39;module.exports&#39;</a>
          </li>
          <li>
            <a href="#function-assigned-to-module-exports-">Function assigned to &#39;module.exports&#39;</a>
          </li>
          <li>
            <a href="#string-number-or-boolean-assigned-to-module-exports-">String, number, or boolean assigned to &#39;module.exports&#39;</a>
          </li>
        </ul>
      </li>
      <li>
        <a href="#values-assigned-to-module-exports-and-local-variables">Values assigned to &#39;module.exports&#39; and local variables</a>
      </li>
      <li>
        <a href="#properties-added-to-this-">Properties added to &#39;this&#39;</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&#39;re documenting Asynchronous Module
      Definition (AMD) modules (also known as &quot;RequireJS modules&quot;), 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&#39;s value should be the module identifier that&#39;s passed to the <code>require()</code> function. For example, if users load
      the module by calling
      <code>require(&#39;my/shirt&#39;)</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&#39;s longname is
      <code>module:my/pants.Jeans#hem</code>.</p>
    <h2 id="properties-of-the-exports-object">Properties of the &#39;exports&#39; object</h2>
    <p>It&#39;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&#39;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&#39;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-module-exports-">Values assigned to &#39;module.exports&#39;</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-module-exports-">Object literal assigned to &#39;module.exports&#39;</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-module-exports-">Function assigned to &#39;module.exports&#39;</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 &#39;module.exports&#39;</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 &#39;module.exports&#39;</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-module-exports-">String, number, or boolean assigned to &#39;module.exports&#39;</h3>
    <p>For value types (strings, numbers, and booleans) assigned to <code>module.exports</code>, you must document the exported value&#39;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-module-exports-and-local-variables">Values assigned to &#39;module.exports&#39; 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 &#39;this&#39;</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&#39;s &#39;this&#39; 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 &#169; 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>