JSDoc

JSDoc is a markup language and tool for writing documentation for JavaScript code. It allows developers to document their code using a simple and standardized syntax, and generates HTML or other formats of documentation based on that documentation.

JSDoc uses a syntax similar to that of JavaDoc and other similar tools, with a few JavaScript-specific extensions. For example, JSDoc allows developers to document the type of a function's parameters and return value using special tags, such as @param and @return. It also allows developers to document class and object properties, modules, and other aspects of their code using similar tags.

/**
 * Adds two numbers.
 *
 * @param {number} x - The first number to add.
 * @param {number} y - The second number to add.
 * @returns {number} The sum of x and y.
 */
function add(x, y) {
  return x + y;
}

jsdoc.json

{
  "source": {
    "include": ["src"],
    "exclude": ["src/vendor"]
  },
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": ["jsdoc", "closure"]
  },
  "opts": {
    "destination": "docs"
  },
  "plugins": ["plugins/markdown"],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false,
    "default": {
      "outputSourceFiles": true
    }
  }
}

for generating documentation. Here's what each option does:

• "source": Specifies the source code directories to document. In this case, we are including the src directory but excluding the src/vendor directory.

• "tags": Specifies how to handle JSDoc tags. In this case, we are allowing unknown tags and specifying the built-in jsdoc and closure tag dictionaries.

• "opts": Specifies options for the output files. In this case, we are specifying the destination directory for the generated documentation.

• "plugins": Specifies plugins to use when generating documentation. In this case, we are using the markdown plugin.

• "templates": Specifies options for the generated documentation's HTML templates. In this case, we are disabling clever and monospace links, and specifying that the output files should include source files.

jsdoc src/my-file.js -c jsdoc.json

META

Status:: #wiki/notes/mature
Plantations:: Node.JS
References:: ILOG