Desarrollo y Mantenimiento de Sistemas Informáticos

4º. 1er cuatrimestre. Itinerario de Sistemas de la Información. Grado en Ingeniería Informática. ULL


Organization DMSI org   Github Classroom DMSI class   Campus Virtual DMSI campus   Profesor Casiano   Chat Chat

documentation is a documentation generator. It’s used to generate documentation from comments within your code. documentation processes JavaScript comments in the JSDoc format.

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

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

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
 * ...

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

 * @param {string} input any string

On the second line:

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

JSDoc lets you specify everything about your code:

Install the documentation binary with npm.

$ npm install -g documentation

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

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"]

References

Documentación.js

Example: ULL-ESIT-DSI-1617/scapegoat

JSDoc

Docco

How to Make Man pages