documentation.js

You can install the documentation binary globally using npm.

$ npm install -g documentation

documentation generates documentation from comments within your code using the JSDoc format.

Important: JSDoc comments must begin with /** (two asterisks). Standard single-line comments (//) or block comments (/*) will be ignored by documentation.`

/**
 * This function adds one to its input.
 * @param {number} input any number
 * @returns {number} that number, plus one.
 */
function addOne(input) {
  return input + 1;
}

When using ES6 destructuring in function parameters (e.g., function({ x, y })), the parent object is unnamed in the code. To document these properties, you must explicitly name the parent object in your JSDoc and use a hierarchical naming convention (prefixing property names with the parent name).

/**
 * This method has hierarchical params
 * @param {Object} animals different kinds of animals
 * @param {String} animals.fishes number of kinds of fish
 */
function fishesAndFoxes({ fishes, foxes }) {
  return fishes + foxes;
}

To indicate that a function parameter is optional and provide a default value, use square brackets [] around the parameter name, followed by =value inside the brackets.

Example syntax: @param {type} [name=defaultValue] description

/**
 * @param {number} [input=5] any number
 */

You can document complex object structures for parameters using brace syntax to show specific allowed values or types.

Example syntax: @param {{key : "value1" | "value2"}}

/**
 * @param {{status : "active" | "inactive" | "inprocess"}}
 */

Configuration is optional, but using a documentation.yml file allows you to organize the order of top-level documentation and insert narrative Markdown sections between autogenerated API documentation. Use the --config command-line option to specify your configuration file.

$ documentation build --config documentation.yml ...

You can integrate documentation.js into your own Node.js applications or build tools (like Gulp or Grunt integrations).

Core Concepts

• Entry Points: The library accepts an array of entry points. An entry point can be a filename (string) or an object containing source (the code string) and file (the filename) members.
• Two-Step Process:
  1. Parsing: Use documentation.build() (asynchronous) or documentation.buildSync() (synchronous) to parse the source code into a documentation object.
  2. Generating Output: Use the documentation.formats object to convert the parsed documentation into specific formats like md, json, or html.

To customize the existing default theme, follow these steps:

1. Copy the contents of the default_theme folder into a new folder in your project (e.g., as a separate git repository).
2. In the new folder's index.js, replace the require('../') calls on lines 8 and 9 with require('documentation').
3. Use the --theme CLI flag to point to your new theme folder.

Example package.json script: "documentation build index.js -f html -o docs --theme node_modules/docjs-theme"

The documentation command provides a build command to generate documentation. You can view the available options for the build command by running documentation --help build.

$ documentation --help build