lint

Lint files for non-standard or incorrect documentation information, returning a potentially-empty string of lint information intended for human-readable output.

Parameters

indexes (Array<string> | string) files to process
args Object args
- args.external Array<string> a string regex / glob match pattern that defines what external modules will be whitelisted and included in the generated documentation.
- args.shallow boolean whether to avoid dependency parsing even in JavaScript code. (optional, default false)
- args.inferPrivate string? a valid regular expression string to infer whether a code element should be private, given its naming structure. For instance, you can specify inferPrivate: '^_' to automatically treat methods named like _myMethod as private.
- args.extension (string | Array<string>)? treat additional file extensions as JavaScript, extending the default set of js, es6, and jsx.

Examples

documentation.lint('file.js').then(lintOutput => {
  if (lintOutput) {
    console.log(lintOutput);
    process.exit(1);
  } else {
    process.exit(0);
  }
});

Returns Promise promise with lint results

build

Generate JavaScript documentation as a list of parsed JSDoc comments, given a root file as a path.

Parameters

indexes (Array<string> | string) files to process
args Object args
- args.external Array<string> a string regex / glob match pattern that defines what external modules will be whitelisted and included in the generated documentation.
- args.shallow boolean whether to avoid dependency parsing even in JavaScript code. (optional, default false)
- args.order Array<(string | Object)> optional array that defines sorting order of documentation (optional, default [])
- args.access Array<string> an array of access levels to output in documentation (optional, default [])
- args.hljs Object? hljs optional args
  - args.hljs.highlightAuto boolean hljs automatically detect language (optional, default false)
  - args.hljs.languages Array? languages for hljs to choose from
- args.inferPrivate string? a valid regular expression string to infer whether a code element should be private, given its naming structure. For instance, you can specify inferPrivate: '^_' to automatically treat methods named like _myMethod as private.
- args.extension (string | Array<string>)? treat additional file extensions as JavaScript, extending the default set of js, es6, and jsx.

Examples

var documentation = require('documentation');

documentation.build(['index.js'], {
  // only output comments with an explicit @public tag
  access: ['public']
}).then(res => {
  // res is an array of parsed comments with inferred properties
  // and more: everything you need to build documentation or
  // any other kind of code data.
});

Returns Promise results

formats

Documentation's formats are modular methods that take comments and config as input and return Promises with results, like stringified JSON, markdown strings, or Vinyl objects for HTML output.

formats.html

Formats documentation as HTML.

Parameters

Examples

var documentation = require('documentation');
var streamArray = require('stream-array');
var vfs = require('vinyl-fs');

documentation.build(['index.js'])
  .then(documentation.formats.html)
  .then(output => {
    streamArray(output).pipe(vfs.dest('./output-directory'));
  });

Returns Promise<Array<Object>> Promise with results

formats.markdown

Formats documentation as Markdown.

Parameters

comments Array<Object> parsed comments
args Object Options that can customize the output

Examples

var documentation = require('documentation');
var fs = require('fs');

documentation.build(['index.js'])
  .then(documentation.formats.md)
  .then(output => {
    // output is a string of Markdown data
    fs.writeFileSync('./output.md', output);
  });

Returns Promise<string> a promise of the eventual value

formats.json

Formats documentation as a JSON string.

Parameters

comments Array<Comment> parsed comments

Examples

var documentation = require('documentation');
var fs = require('fs');

documentation.build(['index.js'])
  .then(documentation.formats.json)
  .then(output => {
    // output is a string of JSON data
    fs.writeFileSync('./output.json', output);
  });

Returns Promise<string>