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

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)
• callback Function to be called when the documentation generation is complete, with (err, result) arguments

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