<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

-   [build](#build)
-   [buildSync](#buildsync)
-   [lint](#lint)
-   [formats](#formats)
-   [formats.html](#formatshtml)
-   [formats.markdown](#formatsmarkdown)
-   [formats.json](#formatsjson)

## build

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

**Parameters**

-   `indexes` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> | [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** files to process
-   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options
    -   `options.external` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** a string regex / glob match pattern
        that defines what external modules will be whitelisted and included in the
        generated documentation.
    -   `options.polyglot` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))>?** optional array that
        defines sorting order of documentation (optional, default `[]`)
    -   `options.access` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>?** an array of access levels
        to output in documentation (optional, default `[]`)
    -   `options.hljs` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** hljs optional options
        -   `options.hljs.highlightAuto` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** hljs automatically detect language (optional, default `false`)
        -   `options.hljs.languages` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)?** languages for hljs to choose from
    -   `options.inferPrivate` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>)?** treat additional file extensions
        as JavaScript, extending the default set of `js`, `es6`, and `jsx`.
-   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** to be called when the documentation generation
    is complete, with (err, result) argumentsj

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** files to process
-   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options
    -   `options.external` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** a string regex / glob match pattern
        that defines what external modules will be whitelisted and included in the
        generated documentation.
    -   `options.polyglot` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))>?** optional array that
        defines sorting order of documentation (optional, default `[]`)
    -   `options.access` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>?** an array of access levels
        to output in documentation (optional, default `[]`)
    -   `options.hljs` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** hljs optional options
        -   `options.hljs.highlightAuto` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** hljs automatically detect language (optional, default `false`)
        -   `options.hljs.languages` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)?** languages for hljs to choose from
    -   `options.inferPrivate` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>)?** treat additional file extensions
        as JavaScript, extending the default set of `js`, `es6`, and `jsx`.
-   `config` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** path to configuration file to load

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> | [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** files to process
-   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options
    -   `options.external` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** a string regex / glob match pattern
        that defines what external modules will be whitelisted and included in the
        generated documentation.
    -   `options.polyglot` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>)?** treat additional file extensions
        as JavaScript, extending the default set of `js`, `es6`, and `jsx`.
-   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** to be called when the documentation generation
    is complete, with (err, result) arguments

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** parsed comments
-   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options that can customize the output
    -   `options.theme` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** Name of a module used for an HTML theme. (optional, default `'default_theme'`)
-   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Called with array of results as vinyl-fs objects.

**Examples**

```javascript
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(err, output) {
    streamArray(output).pipe(vfs.dest('./output-directory'));
  });
});
```

Returns **[undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)** Calls callback.

## formats.markdown

Formats documentation as
[Markdown](http://daringfireball.net/projects/markdown/).

**Parameters**

-   `comments` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** parsed comments
-   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options that can customize the output
-   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** called with null, string

**Examples**

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

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

Returns **[undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)** calls callback

## formats.json

Formats documentation as a JSON string.

**Parameters**

-   `comments` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** parsed comments
-   `opts` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options that can customize the output
-   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** called with null, string

**Examples**

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

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

Returns **[undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)** calls callback