howto-commonjs-modules.html

<!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 &#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-moduleexports">Values assigned to &#39;module.exports&#39;</a>
        <ul>
          <li>
            <a href="#object-literal-assigned-to-moduleexports">Object literal assigned to &#39;module.exports&#39;</a>
          </li>
          <li>
            <a href="#function-assigned-to-moduleexports">Function assigned to &#39;module.exports&#39;</a>
          </li>
          <li>
            <a href="#string-number-or-boolean-assigned-to-moduleexports">String, number, or boolean assigned to &#39;module.exports&#39;</a>
          </li>
        </ul>
      </li>
      <li>
        <a href="#values-assigned-to-moduleexports-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-moduleexports">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-moduleexports">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-moduleexports">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-moduleexports">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-moduleexports-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-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>