NODE_API.md

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
• options Object options
  • options.external Array<string> a string regex / glob match pattern that defines what external modules will be whitelisted and included in the generated documentation.
  • options.polyglot [boolean] parse comments with a regex rather than a proper parser. This enables support of non-JavaScript languages but reduces documentation's ability to infer structure of code. (optional, default false)
  • options.shallow [boolean] whether to avoid dependency parsing even in JavaScript code. With the polyglot option set, this has no effect. (optional, default false)
  • options.order [Array<(string | Object)>] optional array that defines sorting order of documentation (optional, default [])
  • options.access [Array<string>] an array of access levels to output in documentation (optional, default [])
  • options.hljs [Object] hljs optional options
    • options.hljs.highlightAuto [boolean] hljs automatically detect language (optional, default false)
    • options.hljs.languages [Array] languages for hljs to choose from
  • options.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.
  • options.extension [(string | Array<string>)] treat additional file extensions as JavaScript, extending the default set of js, es6, and jsx.
• callback Function to be called when the documentation generation is complete, with (err, result) argumentsj

Examples

var documentation = require('documentation');

documentation.build(['index.js'], {

  // only output comments with an explicit @public tag
  access: ['public']

}, function (err, 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 undefined calls callback

buildSync

Generate JavaScript documentation given a list of inputs. This internal method does not support require-following and it returns its results synchronously, rather than by calling a callback.

Parameters

• indexes Array<string> files to process
• options Object options
  • options.external Array<string> a string regex / glob match pattern that defines what external modules will be whitelisted and included in the generated documentation.
  • options.polyglot [boolean] parse comments with a regex rather than a proper parser. This enables support of non-JavaScript languages but reduces documentation's ability to infer structure of code. (optional, default false)
  • options.shallow [boolean] whether to avoid dependency parsing even in JavaScript code. With the polyglot option set, this has no effect. (optional, default false)
  • options.order [Array<(string | Object)>] optional array that defines sorting order of documentation (optional, default [])
  • options.access [Array<string>] an array of access levels to output in documentation (optional, default [])
  • options.hljs [Object] hljs optional options
    • options.hljs.highlightAuto [boolean] hljs automatically detect language (optional, default false)
    • options.hljs.languages [Array] languages for hljs to choose from
  • options.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.
  • options.extension [(string | Array<string>)] treat additional file extensions as JavaScript, extending the default set of js, es6, and jsx.

Examples

var documentation = require('documentation');

var results = documentation.buildSync(['index.js']);
// results 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 Object list of results

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
• options Object options
  • options.external Array<string> a string regex / glob match pattern that defines what external modules will be whitelisted and included in the generated documentation.
  • options.polyglot [boolean] parse comments with a regex rather than a proper parser. This enables support of non-JavaScript languages but reduces documentation's ability to infer structure of code. (optional, default false)
  • options.shallow [boolean] whether to avoid dependency parsing even in JavaScript code. With the polyglot option set, this has no effect. (optional, default false)
  • options.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.
  • options.extension [(string | Array<string>)] treat additional file extensions as JavaScript, extending the default set of js, es6, and jsx.
• callback Function to be called when the documentation generation is complete, with (err, result) arguments

Examples

documentation.lint('file.js', {}, function (err, lintOutput) {
  if (err) {
    throw err;
  }
  if (lintOutput) {
    console.log(lintOutput);
    process.exit(1);
  } else {
    process.exit(0);
  }
});

Returns undefined calls callback

formats

Documentation's formats are modular methods that take comments and options as input and call a callback with writable objects, like stringified JSON, markdown strings, or Vinyl objects for HTML output.

formats.html

Formats documentation as HTML.

Parameters

• comments Array<Object> parsed comments
• options Object Options that can customize the output
  • options.theme [string] Name of a module used for an HTML theme. (optional, default 'default_theme')
• callback Function Called with array of results as vinyl-fs objects.

Examples

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

documentation.build(['index.js'], {}, function (err, res) {
  documentation.formats.html(res, {}, function(output) {
    streamArray(output).pipe(vfs.dest('./output-directory'));
  });
});

Returns undefined Calls callback.

formats.markdown

Formats documentation as Markdown.

Parameters

• comments Array<Object> parsed comments
• options Object Options that can customize the output
• callback Function called with null, string

Examples

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

documentation.build(['index.js'], {}, function (err, res) {
  documentation.formats.md(res, {}, function(output) {
    // output is a string of JSON data
    fs.writeFileSync('./output.md', output);
  });
});

Returns undefined calls callback

formats.json

Formats documentation as a JSON string.

Parameters

• comments Array<Object> parsed comments
• opts Object Options that can customize the output
• callback Function called with null, string

Examples

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

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

Returns undefined calls callback