archive-gh-me/documentation
1
0
Fork 0
mirror of https://github.com/documentationjs/documentation.git synced 2025-12-08 18:23:43 +00:00
Code Issues Projects Releases Wiki Activity
documentation/docs/NODE_API.md
Tom MacWright 4c66fb14c7 feat(markdown): Add table of contents support for Markdown mode (#645) 
Adds a new option, `--no-markdown-toc`, to turn off Table of Contents generation. Table of contents are now generated by default with markdown output, including through the `readme` command.

Fixes https://github.com/documentationjs/documentation/issues/220
2016-12-28 21:12:33 -05:00

244 lines
15 KiB
Markdown
Raw Blame History

<!-- 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
Reference in New Issue View Git Blame Copy Permalink