How to document a CommonJS module (module.exports)

1. Say you have a CommonJS module you'd like to document.

function add (a, b) {
  return a + b
}

module.exports = add

2. Given that jsdoc2md only generates markdown for documented identifiers and modules, you must document each identifier you want to appear in output - including the module. Therefore, you must use @module at the top of file to document the module.

/**
 * A module for adding two values.
 * @module add-two-values
 */

/**
 * Add two values.
 */
function add (a, b) {
  return a + b
}

module.exports = add

3. Still, the add function above will be documented as an inner of the module - we want it to be documented as the exported value. So, we explicitly declare it as exported by marking it as an @alias of the module:

/**
 * A module for adding two values.
 * @module add-two-values
 */

/**
 * Add two values.
 * @alias module:add-two-values
 */
function add (a, b) {
  return a + b
}

module.exports = add

4. This file will now appear in jsdoc2md output. Without the @module tag it will not appear.

add-two-values

A module for adding two values.

add() ⏏

Add two values.

Kind: Exported function

What not to do

1. Never document module.exports directly. It doesn't work. So, avoid this:

/**
 * Add two values.
 */
module.exports = function add (a, b) {
  return a + b
}