# JSDoc

# jsdoc-to-markdown

jsdoc-to-markdown (opens new window) generates markdown API documentation from jsdoc (opens new window) annotated source code. Useful for injecting API docs into project README files.

1. Document your code using valid jsdoc comments.

/**
 * A quite wonderful function.
 * @param {object} - Privacy gown
 * @param {object} - Security
 * @returns {survival}
 */
function protection (cloak, dagger) {}
1
2
3
4
5
6
7

2. Run a command.

$ jsdoc2md example.js
1

3. Get markdown output.


## protection(cloak, dagger) ⇒ <code>survival</code>
A quite wonderful function.

**Kind**: global function

| Param  | Type                | Description  |
| ------ | ------------------- | ------------ |
| cloak  | <code>object</code> | Privacy gown |
| dagger | <code>object</code> | Security     |

1
2
3
4
5
6
7
8
9
10
11

See also

# Vuepress Autodoc Plugin

See https://bprinty.github.io/vuepress-plugin-autodoc/#overview (opens new window)

# Docco

# How to Make Man pages

# The module documentation.js

documentation (opens new window) is a documentation generator. It's used to generate documentation from comments within your code. documentation processes JavaScript comments in the JSDoc format (opens new window).

➜  scapegoat git:(master) npx documentation --version
13.1.1
1
2

For the most part, the things you document will be functions or classes of JavaScript libraries. Let's start with a function and how to document its essential parts.

  /**
   * Escape special characters in the given string of html
   * @param {string} input any html
   * @returns {string} escaped HTML entities
   */
  function escape(html) {
    if (!html) return '';

    return String(html).replace(specialRe, (match) => reverse[match]);
  },
1
2
3
4
5
6
7
8
9
10

The comment before the escape function is a JSDoc comment. Note that it begins with /** instead of /*. JSDoc requires this.

Let's break down the earlier JSDoc example:

/**
 * Escape special characters in the given string of html
 * ...
1
2
3

The first line of the comment is typically the description. This section says what the code is or does.

 * @param {string} input any string
1

On the second line:

  • @param is a tag: This tag indicates that we'll be documenting a function's parameter.
  • {string} is a type. It says that the input to this function is a JavaScript "string." It could also say {number}, {Object}, {Date}, or any other JavaScript built-in type. And if you defined a custom class, like FooClass, you can use it as a type, too! Just say {FooClass}.
  • input any html is the description of the input.

On the line @returns {string} we just have a description of the value escaped HTML entities.

JSDoc lets you specify everything about your code:

  • use @name to say what something is called,
  • @kind for whether it's a function or a class,
  • @param for its parameters
  • documentation automatically populates @name, @kind, and @memberof tags based on its reading of the code

Install the documentation binary with npm (opens new window).

$ npm install -g documentation
1

documentation then installs a command called documentation. Run it with --help or --help <command> to get help.

➜  scapegoat git:(master) npx documentation help
Usage:

  # generate markdown docs for index.js and files it references
  documentation build index.js -f md

  # generate html docs for all files in src
  documentation build src/** -f html -o docs

  # document index.js, ignoring any files it requires or imports
  documentation build index.js -f md --shallow

  # build, serve, and live-update html docs for app.js
  documentation serve app.js

  # validate JSDoc syntax in util.js
  documentation lint util.js

  # update the API section of README.md with docs from index.js
  documentation readme index.js --section=API

  # build docs for all values exported by index.js
  documentation build --document-exported index.js


Comandos:
  documentation serve [input..]   generate, update, and display HTML
                                  documentation
  documentation build [input..]   build documentation
  documentation lint [input..]    check for common style and uniformity mistakes
  documentation readme [input..]  inject documentation into your README.md

Opciones:
  --version  Muestra número de versión                                [booleano]
  --help     Muestra ayuda                                            [booleano]

Ejemplos:
  documentation build foo.js -f md > API.md
  documentation readme index.js -s "API Docs" --github
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

Here is the help for the build command:

$ documentation --help build

Options:
  --version                  Show version number                       [boolean]
  --help                     Show help                                 [boolean]
  --theme, -t                specify a theme: this must be a valid theme module
  --project-name             project name. by default, inferred from
                             package.json
  --project-version          project version. by default, inferred from
                             package.json
  --project-description      project description. by default, inferred from
                             package.json
  --project-homepage         project homepage. by default, inferred from
                             package.json
  --favicon                  favicon used in html
  --watch, -w                watch input files and rebuild documentation when
                             they change                               [boolean]
  --markdown-toc             include a table of contents in markdown output
                                                       [boolean] [default: true]
  --markdown-toc-max-depth   specifies the max depth of the table of contents in markdown output
                                                           [number] [default: 6]
  --shallow                  shallow mode turns off dependency resolution, only
                             processing the specified files (or the main script
                             specified in package.json)
                                                      [boolean] [default: false]
  --config, -c               configuration file. an array defining explicit sort
                             order                                      [string]
  --no-package, --np         dont find and use package.json for project-
                             configuration option defaults
                                                      [boolean] [default: false]
  --external                 a string / glob match pattern that defines which
                             external modules will be whitelisted and included
                             in the generated documentation.     [default: null]
  --require-extension, --re  additional extensions to include in require() and
                             import's search algorithm.For instance, adding .es5
                             would allow require("adder") to find "adder.es5"
  --parse-extension, --pe    additional extensions to parse as source code.
  --private, -p              generate documentation tagged as private
                                                      [boolean] [default: false]
  --access, -a               Include only comments with a given access level,
                             out of private, protected, public, undefined. By
                             default, public, protected, and undefined access
                             levels are included
                [array] [choices: "public", "private", "protected", "undefined"]
  --github, -g               infer links to github in documentation    [boolean]
  --infer-private            Infer private access based on the name. This is a
                             regular expression that is used to match the name
                                                                        [string]
  --document-exported        Generate documentation for all exported bindings
                             and members even if there is no JSDoc for them
                                                      [boolean] [default: false]
  --sort-order               The order to sort the documentation
                                [choices: "source", "alpha"] [default: "source"]
  --output, -o               output location. omit for stdout, otherwise is a
                             filename for single-file outputs and a directory
                             name for multi-file outputs like html
                                                             [default: "stdout"]
  --format, -f       [choices: "json", "md", "remark", "html"] [default: "json"]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# References about Documentación.js

# Example: ULL-ESIT-DSI-1617/scapegoat

Last Updated: a year ago