NODE_API.md

Table of Contents

• lint
  • Parameters
  • Examples
• build
  • Parameters
  • Examples
• formats
• formats.html
  • Parameters
  • Examples
• formats.json
  • Parameters
  • Examples
• formats.markdown
  • Parameters
  • Examples

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

• comments Array<Comment> parsed comments
• config Object Options that can customize the output
  • config.theme string Name of a module used for an HTML theme. (optional, default 'default_theme')

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

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