.. _amd-modules:

Amd Modules
===================

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

JSDoc 3 makes it possible to document modules that use the `Asynchronous
Module Definition (AMD)
API <https://github.com/amdjs/amdjs-api/blob/master/AMD.md>`__, which is
implemented by libraries such as `RequireJS <http://requirejs.org/>`__.
This page explains how to document an AMD module for JSDoc, based on the
coding conventions that your module uses.

If you’re documenting CommonJS or Node.js modules, see :ref:`commonjs-modules` for instructions.

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

When you document an AMD module, you’ll use an :rst:dir:`@exports` or :rst:dir:`@module` to
document the identifier that’s passed to the ``require()`` function. For
example, if users load the module by calling
``require('my/shirt', /* callback */)``, you’ll write a JSDoc comment
that contains the tag ``@exports my/shirt`` or ``@module my/shirt``. The
examples below can help you decide which of these tags to use.

If you use the :rst:dir:`@exports` or :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:`namepath` 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``.

Function that returns an object literal
---------------------------------------

If you define your AMD module as a function that returns an object
literal, use the :rst:dir:`@exports` to document
the module’s name. JSDoc will automatically detect that the object’s
properties are members of the module.

.. code-block:: js
   :caption: Function that returns an object literal

   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;
   });

Function that returns another function
--------------------------------------

If you define your module as a function that exports another function,
such as a constructor, you can use a standalone comment with a
:rst:dir:`@module` to document the module. You can
then use an :rst:dir:`@alias` to tell JSDoc that the
function uses the same longname as the module.

.. code-block:: js
   :caption: Function that returns a constructor

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

Module declared in a return statement
-------------------------------------

If you declare your module object in a function’s ``return`` statement,
you can use a standalone comment with a :rst:dir:`@module` to document the module.
You can then add an :rst:dir:`@alias` to tell JSDoc that the module object has the same longname as the module.

.. code-block:: js
   :caption: Module declared in a return statement

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

Module object passed to a function
----------------------------------

If the module object is passed into the function that defines your
module, you can document the module by adding an :rst:dir:`@exports` to the function parameter. This pattern is
supported in JSDoc 3.3.0 and later.

.. code-block:: js
   :caption: Module object passed to a function

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

Multiple modules defined in one file
------------------------------------

If you define more than one AMD module in a single JavaScript file, use
the :rst:dir:`@exports` to document each module object.

.. code-block:: js
   :caption: Multiple AMD modules defined in one file

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