.. _commonjs-modules:

CommonJS Modules
======================

Overview
-----------

To help you document `CommonJS modules <http://wiki.commonjs.org/wiki/Modules/1.1>`_, JSDoc 3
understands many of the conventions used in the CommonJS specification
(for example, adding properties to the ``exports`` object). In addition,
JSDoc recognizes the conventions of `Node.js modules <http://nodejs.org/api/modules.html>`_, which extend the
CommonJS standard (for example, assigning a value to ``module.exports``). Depending on the coding conventions you follow,
you may need to provide some additional tags to help JSDoc understand your code.

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 :rst:dir:`amd-modules`.

Module identifiers
------------------

In most cases, your CommonJS or Node.js module should include a
standalone JSDoc comment that contains a :rst:dir:`@module`. The :rst:dir:`@module` tag’s value should be the
module identifier that’s passed to the ``require()`` function. For
example, if users load the module by calling ``require('my/shirt')``,
your JSDoc comment would contain the tag ``@module my/shirt``.

If you use the :rst:dir:`@module` tag without a value, JSDoc will try to guess
the correct module identifier based on the filepath.

When you use a JSDoc :ref:`namepaths` to refer to a
module from another JSDoc comment, you must add the prefix ``module:``.
For example, if you want the documentation for the module ``my/pants``
to link to the module ``my/shirt``, you could use the :rst:dir:`@see` to document ``my/pants`` as follows:

.. code-block:: js

   /**
    * Pants module.
    * @module my/pants
    * @see module:my/shirt
    */

Similarly, the namepath for each member of the module will start with
``module:``, followed by the module name. For example, if your
``my/pants`` module exports a ``Jeans`` constructor, and ``Jeans`` has
an instance method named ``hem``, the instance method’s longname is
``module:my/pants.Jeans#hem``.

Properties of the ‘exports’ object
----------------------------------

It’s easiest to document symbols that are directly assigned to a
property of the ``exports`` object. JSDoc will automatically recognize
that the module exports these symbols.

In the following example, the ``my/shirt`` module exports the methods
``button`` and ``unbutton``. JSDoc will automatically detect that the
module exports these methods.

.. code-block:: js
   :caption: Methods added to the exports object

   /**
    * Shirt module.
    * @module my/shirt
    */

   /** Button the shirt. */
   exports.button = function() {
       // ...
   };

   /** Unbutton the shirt. */
   exports.unbutton = function() {
       // ...
   };

## Values assigned to local variables

In some cases, an exported symbol may be assigned to a local variable
before it’s added to the ``exports`` object. For example, if your module
exports a ``wash`` method, and the module itself often calls the
``wash`` method, you might write the module as follows:

.. code-block:: js
   :caption: Method assigned to a local variable and added to the exports object

   /**
    * Shirt module.
    * @module my/shirt
    */

   /** Wash the shirt. */
   var wash = exports.wash = function() {
       // ...
   };

In this case, JSDoc will *not* automatically document ``wash`` as an
exported method, because the JSDoc comment appears immediately before
the local variable ``wash`` rather than ``exports.wash``. One solution
is to add an :rst:dir:`@alias` that defines the
correct longname for the method. In this case, the method is a static
member of the module ``my/shirt``, so the correct longname is
``module:my/shirt.wash``:

.. code-block:: js
   :caption: Longname defined in an @alias tag

   /**
    * Shirt module.
    * @module my/shirt
    */

   /**
    * Wash the shirt.
    * @alias module:my/shirt.wash
    */
   var wash = exports.wash = function() {
       // ...
   };

Another solution is to move the method’s JSDoc comment so it comes
immediately before ``exports.wash``. This change allows JSDoc to detect
that ``wash`` is exported by the module ``my/shirt``:

.. code-block:: js
   :caption: JSDoc comment immediately before exports.wash

   /**
    * Shirt module.
    * @module my/shirt
    */

   var wash =
   /** Wash the shirt. */
   exports.wash = function() {
       // ...
   };

Values assigned to ‘module.exports’
-----------------------------------

In a Node.js module, you can assign a value directly to
``module.exports``. This section explains how to document different
types of values when they are assigned to ``module.exports``.

Object literal assigned to ‘module.exports’
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If a module assigns an object literal to ``module.exports``. JSDoc
automatically recognizes that the module exports only this value. In
addition, JSDoc automatically sets the correct longname for each
property:

.. code-block:: js
   :caption: Object literal assigned to module.exports

   /**
    * 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) {
           // ..
       }
   };

You can also use this pattern if you add properties to ``module.exports`` outside of the object literal:

.. code-block:: js
   :caption: Assignment to module.exports followed by property definition

   /**
    * 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) {
       // ..
   };

Function assigned to ‘module.exports’
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you assign a function to ``module.exports``, JSDoc will automatically
set the correct longname for the function:

.. code-block:: js
   :caption: Function assigned to ‘module.exports’

   /**
    * 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) {
       // ...
   };

The same pattern works for constructor functions:

.. code-block:: js
   :caption: Constructor assigned to ‘module.exports’

   /**
    * Color mixer.
    * @module color/mixer
    */

   /** Create a color mixer. */
   module.exports = function ColorMixer() {
       // ...
   };

String, number, or boolean assigned to ‘module.exports’
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For value types (strings, numbers, and booleans) assigned to ``module.exports``,
you must document the exported value’s type by using the :rst:dir:`@type` in the same JSDoc comment as the :rst:dir:`@module` tag:

.. code-block:: js
   :caption: String assigned to module.exports

   /**
    * Module representing the word of the day.
    * @module wotd
    * @type {string}
    */

   module.exports = 'perniciousness';

Values assigned to ‘module.exports’ and local variables
-------------------------------------------------------

If your module exports symbols that are not directly assigned to ``module.exports``,
you can use the :rst:dir:`@exports` in place of the :rst:dir:`@module` tag.
The :rst:dir:`@exports` tag tells JSDoc that a symbol represents the value exported by a module.


.. code-block:: js
   :caption: Object literal assigned to a local variable and module.exports

   /**
    * 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) {
           // ...
       }
   };

Properties added to ‘this’
--------------------------

When a module adds a property to its ``this`` object,
JSDoc 3 automatically recognizes that the new property is exported by the module:

.. code-block:: js
   :caption: Properties added to a module’s ‘this’ object

   /**
    * 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;
   }