Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

documentation

documentationjs200.2kISC14.0.3

a documentation generator

documentation, formatter, jsdoc, jsdoc3, parser, website

readme

The documentation system for modern JavaScript

Circle CI npm version Gitter Inline docs

:date: Current maintenance status

  • Supports modern JavaScript: ES5, ES2017, JSX, Vue and Flow type annotations.
  • Infers parameters, types, membership, and more. Write less documentation: let the computer write it for you.
  • Integrates with GitHub to link directly from documentation to the code it refers to.
  • Customizable output: HTML, JSON, Markdown, and more

Examples

Documentation

User Guide

Globally install documentation using the npm package manager:

$ npm install -g documentation

This installs a command called documentation in your path, that you can point at JSDoc-annotated source code to generate human-readable documentation. First, run documentation with the --help option for 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, and include links to source files in github
documentation build src/** -f html --github -o docs

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

# 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

# build html docs for a TypeScript project
documentation build index.ts --parse-extension ts -f html -o docs

Commands:
  build [input..]   build documentation
  lint [input..]    check for common style and uniformity mistakes
  readme [input..]  inject documentation into your README.md

Options:
  --version  Show version number                                       [boolean]
  --help     Show help                                                 [boolean]

Contributing

We have plenty of issues that we'd love help with.

  • Robust and complete JSDoc support, including typedefs.
  • Strong support for HTML and Markdown output
  • Documentation coverage, statistics, and validation

documentation is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

changelog

Changelog

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

14.0.3 (2024-01-30)

Bug Fixes

14.0.2 (2023-05-19)

Bug Fixes

14.0.1 (2022-12-14)

Improvements

  • chore: upgrade git-url-parse to 13.1.0 to fix vulnerabilities #1565

14.0.0 (2022-08-19)

14.0.0-alpha.1 (2022-08-07)

Features

  • :sparkles: update Babel, copy list of plugins from Prettier (3f187d7)

14.0.0-alpha.0 (2022-08-05)

⚠ BREAKING CHANGES

  • all Extensions should contains '.' so that mean if you have just 'ts' then need to convert to '.ts'
  • external parameter was removed Migration plan propose to move all external resources to input usages Motivation: packages has many inputs which describe in package.json so that mean need each time to parse all package.json of external resources to understand which entry point need to pick. But it is base on guesses because entry point may could not contains a documentation and the best way to handle it manually.
  • The serve parameter was removed, you can use any other tools which could be refresh and store your html site The private parameter has removed, use a access
  • documentation.js will now require node 14 or later.

Bug Fixes

  • add micromark dependencies fixed #1381 (3ba8165)
  • add TS and TSX as default extensions fixed #1377 (f0cb1c0)
  • external was removed as prefer of input usages (e3c59d7)
  • html report, it is return html if output is not defined (0975871)
  • remove private parameter, use access (BREAKING CHANGES) (874069c)
  • The server parameter deprecated and will be remove in next Major version fixed #1413 (810e08b)
  • use process.cwd vs . which can fail (4cc70a5)
  • replace module-deps-sortable on own implementation to control how parse files (abb781a)
  • Update Node minimum version to 14 (fc0bb3c)

13.2.5 (2021-04-24)

Bug Fixes

13.2.4 (2021-04-21)

Bug Fixes

13.2.3 (2021-04-20)

13.2.2 (2021-04-20)

Bug Fixes

13.2.1 (2021-04-06)

13.2.0 (2021-03-13)

Features

13.1.1 (2021-01-19)

13.1.0 (2020-10-24)

Features

13.0.2 (2020-07-02)

Bug Fixes

  • Additional safety around detecting functions in HTML output (a8b6ce1)

13.0.1 (2020-06-04)

Bug Fixes

  • 🐛 Error with flow opaque type and readme command (78db9a4), closes #1322
  • 🐛 Fixes an issue when using object spread and $Exact (106945c), closes #1324

13.0.0 (2020-05-09)

Chores

  • Update Node minimum version to 10 (45a5257)

BREAKING CHANGES

  • documentation.js will now require node 10 or later.

12.3.0 (2020-04-07)

Features

  • upgrade babel dependencies (d0ec029)

12.2.0 (2020-03-31)

Features

  • support for the @see tag in Markdown & HTML (48bb7a2)

12.1.4 (2019-11-15)

12.1.3 (2019-11-04)

Bug Fixes

  • upgrade git-url-parse to fix a parsing issue (#1296) (344e804)

12.1.2 (2019-09-09)

Bug Fixes

12.1.1 (2019-08-01)

Bug Fixes

  • Git submodule support for repo names with a dot (#1271) (27a29be)

12.1.0 (2019-07-31)

Features

  • Add git submodules support to github linking (#1270) (ec36b41)

12.0.3 (2019-07-22)

Bug Fixes

12.0.2 (2019-07-16)

12.0.1 (2019-07-10)

Bug Fixes

  • Crash when called with no inputs. yargs now variadic positional arguments undefined instead of [] (821a15e)

12.0.0 (2019-07-10)

  • Formatted with Prettier (8f36e75)

BREAKING CHANGES

  • The next release will require Node 8

11.0.1 (2019-06-12)

Bug Fixes

  • toc with children getting displayed as "note" (#1253) (14298bb)

11.0.0 (2019-05-08)

Bug Fixes

  • Fix parsing of optional parameters with annotations (ca17de5)

Features

  • Enable all parser plugins (fa1b0b5)
  • Support exportNamespaceFrom in parser (8fa141d)

BREAKING CHANGES

  • this removes support for legacy decorators, because in one place we had legacy and in another we didn't.

10.1.0 (2019-04-25)

Features

  • TypeScript support & inference (3773e02)

10.0.0 (2019-04-18)

Features

  • Add flow inference for generators (7947e97)
  • Support async functions (d31c3b7)
  • Support classPrivateProperties in parser (64ef671), closes #1216
  • Support generator functions (8e3cd47)

10.0.0-alpha.0 (2019-03-12)

Features

BREAKING CHANGES

  • this may change babel configuration loading, and is a major change to the documentation.js approach to Babel.

9.3.1 (2019-03-12)

9.3.0 (2019-02-27)

Features

9.2.1 (2019-02-26)

9.2.0 (2019-02-22)

Bug Fixes

Features

9.1.1 (2018-12-21)

Bug Fixes

  • inferred properties duplicating explicitly specified ones (2d0bd0e)

9.1.0 (2018-12-17)

Features

9.0.0 (2018-12-10)

Features

  • Support for the logical assignment operator (58d2a2f), closes #1172

9.0.0-alpha.1 (2018-10-24)

Bug Fixes

Features

  • add support for node resolve algo (ddd675d)

9.0.0-alpha.0 (2018-09-21)

Features

BREAKING CHANGES

  • This moves documentation.js to Babel 7. From now on, documentation.js will only support Babel 7: please stick to older releases if you need to support Babel 6. Additionally, this work temporarily disables support for following dynamic imports.

8.1.2 (2018-08-23)

Bug Fixes

8.1.1 (2018-08-17)

Bug Fixes

8.1.0 (2018-08-03)

Bug Fixes

  • package: update get-port to version 4.0.0 (9ca8c06)

Features

  • added project description (45a9ea9)

8.0.2 (2018-07-20)

Bug Fixes

  • package: update git-url-parse to version 10.0.1 (91ade89)

8.0.1 (2018-07-16)

Bug Fixes

  • package: update read-pkg-up to version 4.0.0 (c700d3f)

8.0.0 (2018-06-04)

Features

BREAKING CHANGES

  • changes Markdown output

7.1.0 (2018-05-26)

Features

  • support flow comment types (85d50f9)

7.0.0 (2018-05-22)

Features

  • Auto-detect readme filename (4fd776b)

BREAKING CHANGES

  • the --readme-file option now has a smart default value

6.3.3 (2018-05-14)

6.3.2 (2018-04-24)

Bug Fixes

  • vue: Make vue parser tolerant of components that don't contain scripts (#1061) (8f9bc7b), closes #1060

6.3.1 (2018-04-23)

Bug Fixes

  • adding vue support broke tests that are not file based (#1058) (9d7bd2e), closes #1057

6.3.0 (2018-04-20)

Bug Fixes

  • package: update git-url-parse to version 9.0.0 (94a1fb6)

Features

6.2.0 (2018-04-11)

Bug Fixes

  • get rid of shelljs dependency (630625d)

Features

  • doctrine: Support decorator syntax in examples (b309d39), closes #1016
  • inferTypes: Support class properties (22d8740), closes #1043

6.1.0 (2018-03-08)

Bug Fixes

  • lends with object property using literal key (#1035) (99ad49b)

Features

6.0.0 (2018-03-02)

Features

  • documentation.js now requires node v6 or newer. (#1034) (ccce516)

BREAKING CHANGES

  • documentation.js requires node v6 or newer.

5.5.0 (2018-03-02)

Bug Fixes

  • github links for @typedef comments should link to comment, not context (#1024) (37a91b2)
  • Make documentation.js compatible with node 4.x for one more version (#1033) (5067ee0)

Features

  • Support --shallow argument for lint command. Closes #956 (#995) (64f660d)
  • Support the .mjs extension by default. (#1023) (b8a7e0d)
  • use reference links for Markdown output, improving brevity (ab494dd)

5.4.0 (2018-02-10)

Bug Fixes

  • package: update remark-toc to version 5.0.0 (0bb3d0d)

Features

  • add support for class param declarations at the constructor (#1013) (05c5279)

5.3.5 (2017-12-12)

Bug Fixes

5.3.4 (2017-12-12)

Bug Fixes

  • package: update babelify to version 8.0.0 (10dff6f)
  • package: update read-pkg-up to version 3.0.0 (d8fbf2c)
  • package: update remark-html to version 7.0.0 (9842814)
  • package: update vinyl-fs to version 3.0.0 (#966) (1d6fe80)

5.3.3 (2017-10-12)

Bug Fixes

  • html: Display all levels of parameter properties. (#933) (7a548eb)
  • package: update github-slugger to version 1.2.0 (2b74956)
  • Fix the split in HTML at 33/67% instead of calculating percentages (#939) (e4781eb), closes #927

5.3.2 (2017-09-15)

Bug Fixes

  • special property names in flowtypes (7fc6ca8)

5.3.1 (2017-09-07)

Bug Fixes

  • cover more hideconstructor cases (5bdbf1f)
  • Enable dynamicImport plugin to support import() syntax (#903) (b97241f), closes #902
  • regression in toc causing crash (125a577)

5.3.0 (2017-09-04)

Bug Fixes

Features

5.2.2 (2017-08-22)

Bug Fixes

  • $compile: prevent babel from transpiling non-module scripts in default_theme's assets (1286a1f)

5.2.1 (2017-08-12)

5.2.0 (2017-08-09)

Bug Fixes

  • alphabetical sort and add flow notation to sort file (#861) (aa3496a), closes #838
  • make html and markdown second option optional (#871) (0324865), closes #869

Features

  • convert Flow's ThisTypeAnnotation to a doctrine NameExpression (#870) (23aa981)

5.1.1 (2017-08-04)

Bug Fixes

  • theme: Remove dead stepsibling navigation code (dccb151)
  • cli options should override package.json options (ecf16bd), closes #845

5.1.0 (2017-07-31)

Bug Fixes

  • scripts: Remove changelog package.json task (dddac19)

Features

  • theme: Flexible sidebar for default theme (6509ae8)

5.0.1 (2017-07-28)

5.0.0 (2017-07-27)

Reverts

BREAKING CHANGES

  • polyglot: I'd like to still support C++ and other languages in the future! But I'm much happier doing so by separating the extraction & input phases to the degree that documentation.js can read the output of another module that extracts JSDoc comments from C++ code, rather than having CPP support in it.

4.0.0 (2017-07-27)

Bug Fixes

  • html output: Fix links between navigation and items in HTML documentation (5fb77bc)
  • package: update babel-generator to version 6.25.0 (#804) (65f5a37)
  • package: update chalk to version 2.0.0 (#833) (2329db4)
  • package: update github-slugger to version 1.1.3 (#793) (74392cc)
  • Show () for callbacks (61968c7)
  • package: update micromatch to version 3.0.0 (#792) (3f2bf90)
  • package: update remark to version 8.0.0 (1ae8136)
  • Fix filtering in the default theme (473f317)
  • Report nesting errors instead of throwing them as errors (ea69608), closes #832
  • package: update remark-html to version 6.0.1 (#815) (e472550)
  • package: update vfile-reporter to version 4.0.0 (a3e1fb8)

4.0.0-rc.1 (2017-05-01)

Bug Fixes

  • Infer parameters for classes from constructors (355038d), closes #689
  • document-exported: Ensure that document-exported does not document constructors separately (96a6d13)
  • flow: Fix inference of Flow types with properties (#751) (7c00acc), closes #749
  • params: Parameters with default use = not ? (3cc4426), closes #737

Features

  • lint: Identify explicit tags that don't match inference in lint stage (ed5c2a0)

4.0.0-rc.0 (2017-04-21)

Bug Fixes

  • html output: Fix github links in HTML output (#745) (9554b2f), closes #738
  • params: added code path for type RestElement (6961ee8)

Code Refactoring

BREAKING CHANGES

  • nest: referencing inferred destructure params without renaming them, like $0.x, from JSDoc comments will no longer work. To reference them, instead add a param tag to name the destructuring param, and then refer to members of that name.

Before:

/**
 * @param {number} $0.x a member of x
 */
function a({ x }) {}

After:

/**
 * @param {Object} options
 * @param {number} options.x a member of x
 */
function a({ x }) {}

  • Address review comments

  • Reduce testing node requirement back down to 4

  • Don't output empty properties, reduce diff noise

  • Rearrange and document params

  • Simplify param inference, update test fixtures. This is focused around Array destructuring: documenting destructured array elements with indices instead of names, because the names are purely internal details

  • Use temporary fork to get through blocker

4.0.0-beta.19 (2017-04-10)

Bug Fixes

  • inference: Refactor membership inference (84c9215)
  • inference: Robust parsing for shorthand object methods (802dc4c)
  • scopes: Support inner scope (#665) (8cc34b6)

Features

  • core: Support Flow interface declarations (e2915dc)
  • core: Switch to Promises everywhere. Adopt Node v4 ES6 (#648) (631c692)
  • markdown: Add [@see](https://github.com/see) tag output in Markdown (#682) (f07285a)

4.0.0-beta.18 (2016-12-29)

Bug Fixes

  • cli: Fix error reporting in the CLI (88c8f9a)
  • markdown: Start headings in Markdown at h2 (#644) (2ae5d8f)

Features

  • bin: Support globs on windows and use smarter recursion (#629) (cb8fdfa), closes #607
  • markdown: Add table of contents support for Markdown mode (#645) (4c66fb1)

Performance Improvements

  • dependencies: Move standard-changelog to devDependencies (#636) (7a66b3f)

4.0.0-beta.17 (2016-12-23)

This release also fixes a mistake I was making with semver: pre-v4 beta releases will be called beta.17 and beta.18 and so on, rather than non-standard beta16 without the ..

Bug Fixes

  • hierarchy: collect events from static and instance members (#628) (f1e0267), closes #486

4.0.0-beta16 (2016-12-07)

Bug Fixes

  • bin: Remove dead code in documentation.js command (#627) (ab16a20)
  • extractors: Document export default value (#623) (363a108), closes #543
  • parser: Avoid error about deoptimization on very large files (#621) (846ab94)

Features

  • build: load passed in config option (#625) (89fb67f)
  • output: Display type information for typedefs in Markdown and HTML (8b04029)

4.0.0-beta15 (2016-11-23)

Fixes

  • Infer class augments tag in cases like Foo extends React.Component

Features

4.0.0-beta14

  • Highlight all Markdown, not just examples. Fixes #610
  • Fix for --config only strip comments on json files (#611)
  • Merge inferred return type like we do for params. Refs #359 (#604)
  • Support webpack's System.import with nice handy babel plugin (#603)
  • Format optional types with ? instead of [] (#538)
  • Fix membership assignment for old-fashioned prototype members (#599)
  • Update Node API documentation to include only exposed API surface
  • Add too-much-inference troubleshooting topic

4.0.0-beta13

  • Fix linker null reference error

4.0.0-beta12

  • Update Doctrine to handle more JSDoc types
  • Fix ReferenceError in default theme
  • Show GitHub link for nested elements in default theme
  • Fix linking resolution order

4.0.0-beta11

4.0.0-beta10

  • Lower memory consumption when dealing with large codebases
  • Better support for detecting names and kinds of ES6-exported values
  • New document-exported flag allows you to automatically document ES6-exported values, without even a comment! 490

4.0.0-beta5

  • Add decorator support (zacharygolba)
  • Add support to infer whether functions are private based on their name, like starting with _ (arv)
  • Improve internal documentation

4.0.0-beta4

  • Fix minor dependency mistake

4.0.0-beta3

  • Updates theme to a much-improved design
  • Fix augments tag display in HTML
  • Improve name detection of ES6-exported methods and variables
  • Allow documentation of Object.prototype methods

4.0.0-beta2

Minor fixes

  • Fixes export { foo } from './bar' style export
  • Fixed CLI usage examples to simply say documentation instead of /usr/bin/documentation or similar.

4.0.0-beta1

Now using Babel 6!

Much long-awaited upgrade makes documentation.js compatible with fresh new Babel-using codebases.

And also:

  • GitHub Enterprise support
  • New tag support: abstract, override, readonly, interface, variation, see, todo (only in parsing phase, not yet in all outputs)
  • Parses jsx and es6 extensions by default, as well as .js
  • Fixes polyglot mode
  • Now shows the @throws tag content in Markdown output
  • Support for example captions

4.0.0-beta

Revitalized documentation.js command line interface!

The documentation utility now takes commands:

  • documentation build extracts and formats documentation
  • documentation serve provides an auto-reloading server (#236)
  • documentation lint reviews files for inconsistencies
  • documentation readme patches API documentation into a readme (#313 by @anandthakker)

This functionality was previously included in dev-documentation and has been folded into documentation proper.

Much more flexible themes

Themes are now much more customizable. In documentation.js 3.x and before, themes were required to use Handlebars templates and produce a single page. In documentation.js 4.x and beyond, they are JavaScript modules that can use any template engine and produce any number of files. See the new theme documentation for details.

More precise traversal

Inference in 4.x is stricter than in 3.x: comments must be adjacent to the statements they document. This should make documentation generation much more predictable.

Support for the revealing module pattern

/** Foo */
function Foo() {
  /** Test */
  function bar() {}
  return {
    bar: bar
  };
}
`

New support for the JavaScript module pattern! This was implemented in #324 by Charlie Brown.

Breaking changes

3.0.4

  • Allow parameter types to be mixed into explicit parameter documentation. (#239 and #232)
  • Support GitHub links in Markdown output (#238)

3.0.3

  • Infer typedefs from Flow type aliases. Fixes #227
  • Fix type-annotated rest expressions, raised in #230

3.0.2

  • Infer rest parameters. Fixes #223
  • Avoid filtering comments in lint mode. Fixes #186
  • Nest both properties and params. Fixes #164

3.0.1

  • BUGFIX: Fix default theme resolution #212

3.0.0

The largest change to documentation.js so far.

Dropping streams

This a major refactor of the documentation.js interface with a focus on simplifying the system. Up until this point, documentation.js was built around node.js streams, which are low-level representations of asynchronous series of data. While this abstraction was appropriate for the input and github streams, which are asynchronous, the majority of documentation.js's internals are simple and synchronous functions for which basic functional composition makes more sense than stream semantics.

Documentation 3.0.0 uses simple functional composition for operations like parmameter inference, rather than streams.

Stronger support for ES6, ES7, and Flow

We've switched to Babel as our source code parser, which means that we have much broader support of new JavaScript features, including import/export syntax and new features in ES6.

Babel also parses Flow type annotations, and new inference code means that we can infer

  • Parameter names & types
  • Return types

Without any explicit JSDoc tags. This means that for many simple functions, we can generate great documentation with less writing.

Stronger module support

Documentation.js now has much better inference for membership and names of symbols exported via exports or module.exports.

Support for nested symbols

The parent/child relationship between symbols is now fully hierarchical, and symbols can be nested to any depth. For instance:

/**
 * A global Parent class.
 */
var Parent = function () {};

/**
 * A Child class.
 */
Parent.Child = function () {};

/**
 * A Grandchild class.
 */
Parent.Child.Grandchild = function () {};

In addition, filtering by access is now applied to the entire hierarchy: if you mark a class as @private, neither it nor its children will be included in the output by default, regardless of the access specifiers of the children.

mdast-based Markdown output

We've switched from templating Markdown output with Handlebars.js to generating an abstract syntax tree of desired output and stringifying it with mdast. This lets documentation.js output complex Markdown without having to worry about escaping and properly formatting certain elements.

Test coverage 100%

documentation.js returns to 100% test coverage, so every single line of code is covered by our large library of text fixtures and specific tests.

--lint mode

Specifying the --lint flag makes documentation.js check for non-standard types, like String, or missing namespaces. If the encountered files have any problems, it pretty-prints helpful debug messages and exits with status 1, and otherwise exits with no output and status 0.

Breaking changes

  • The --version flag is now --project-version. --version now outputs documentation.js's version

2.0.1

  • Fixes @param tags that refer to properties of unmentioned objects: these will warn instead of crashing. For instance, /** @param {boolean} foo.bar */.
  • Expose --shallow option in CLI

2.0.0

  • Breaking: Removes docset support from documentation.js: this will be supported by a 3rd party tool in the future. This removal means that we no longer have node-sqlite3 as a dependency, and documentation can be installed on systems without a compile toolchain.
  • JSDoc parse errors are now printed to stderr.
  • Parameter tags that document sub-parameters, such as @param {Type} options.option, are now nested under their parent parameter.
  • HTML output now includes events.
  • Error messages now include source file name and line number.
  • @typedef names are now inferred correctly.

1.4.0

  • Output for the @throws tag.
  • Output in HTML for the @properties tag.

1.3.0

/**
 * @param {Type} [param=defaultValue]
 */

1.2.0

  • Transforms in package.json browserify.transform fields are now applied to source code so that babel, etc can be supported.
  • Fixes crash caused by requiring JSON files

1.1.0

  • Add external option that allows the user to whitelist specific external modules to be included in with documentation.

1.0.7

  • Fixes sorting order of documentation
  • Switches order of static and instance members in output