diff --git a/docs/NODE_API.md b/docs/NODE_API.md index e509a838c..8be51f979 100644 --- a/docs/NODE_API.md +++ b/docs/NODE_API.md @@ -2,163 +2,105 @@ ### Table of Contents -- [build](#build) -- [buildSync](#buildsync) - [lint](#lint) +- [build](#build) - [formats](#formats) - [formats.html](#formatshtml) - [formats.markdown](#formatsmarkdown) - [formats.json](#formatsjson) -## build +## lint -Generate JavaScript documentation as a list of parsed JSDoc -comments, given a root file as a path. +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)<[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)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** a string regex / glob match pattern +- `args` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** args + - `args.external` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[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 + - `args.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 + - `args.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)<([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)<[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 + - `args.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)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>)?** treat additional file extensions + - `args.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)<[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. - +documentation.lint('file.js').then(lintOutput => { + 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 +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** promise with lint results -## buildSync +## build -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. +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)<[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)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** a string regex / glob match pattern +- `indexes` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[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 +- `args` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** args + - `args.external` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[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 + - `args.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 + - `args.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)<([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 + - `args.order` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<([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)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>?** an array of access levels + - `args.access` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[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 + - `args.hljs` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** hljs optional args + - `args.hljs.highlightAuto` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** hljs automatically detect language (optional, default `false`) + - `args.hljs.languages` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)?** languages for hljs to choose from + - `args.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)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>)?** treat additional file extensions + - `args.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)<[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)<[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)<[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)<[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); - } +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 **[undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)** calls callback +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** results ## formats Documentation's formats are modular methods that take comments -and options as input and call a callback with writable objects, +and config as input and return Promises with results, like stringified JSON, markdown strings, or Vinyl objects for HTML output. @@ -168,10 +110,9 @@ Formats documentation as HTML. **Parameters** -- `comments` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[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. +- `comments` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Comment](https://developer.mozilla.org/en-US/docs/Web/API/Comment/Comment)>** parsed comments +- `config` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options that can customize the output + - `config.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'`) **Examples** @@ -180,14 +121,14 @@ 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) { +documentation.build(['index.js']) + .then(documentation.formats.html) + .then(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. +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>>** Promise with results ## formats.markdown @@ -197,8 +138,7 @@ Formats documentation as **Parameters** - `comments` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[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 +- `args` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options that can customize the output **Examples** @@ -206,15 +146,15 @@ Formats documentation as 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 +documentation.build(['index.js']) + .then(documentation.formats.md) + .then(output => { + // output is a string of Markdown data fs.writeFileSync('./output.md', output); }); -}); ``` -Returns **[undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)** calls callback +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** a promise of the eventual value ## formats.json @@ -222,9 +162,7 @@ Formats documentation as a JSON string. **Parameters** -- `comments` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[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 +- `comments` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Comment](https://developer.mozilla.org/en-US/docs/Web/API/Comment/Comment)>** parsed comments **Examples** @@ -232,12 +170,12 @@ Formats documentation as a JSON string. var documentation = require('documentation'); var fs = require('fs'); -documentation.build(['index.js'], {}, function (err, res) { - documentation.formats.json(res, {}, function(err, output) { +documentation.build(['index.js']) + .then(documentation.formats.json) + .then(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 +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** diff --git a/package.json b/package.json index 1282ab71c..917329c3a 100644 --- a/package.json +++ b/package.json @@ -102,7 +102,7 @@ "release": "standard-version", "precommit": "lint-staged --verbose", "format": "prettier --write '{src,__tests__,declarations,bin,default_theme}/**/*.js' --single-quote", - "doc": "./bin/documentation.js build lib/index.js -f md --access=public > docs/NODE_API.md", + "doc": "./bin/documentation.js build src/index.js -f md --access=public > docs/NODE_API.md", "changelog": "standard-changelog -i CHANGELOG.md -w", "self-lint": "node ./bin/documentation.js lint src", "test": "npm run build && eslint . && are-we-flow-yet src && flow check && jest",