diff options
Diffstat (limited to 'tools/eslint/node_modules/doctrine/README.md')
| -rw-r--r-- | tools/eslint/node_modules/doctrine/README.md | 138 |
1 files changed, 68 insertions, 70 deletions
diff --git a/tools/eslint/node_modules/doctrine/README.md b/tools/eslint/node_modules/doctrine/README.md index bade0907b6..14e3dfe68c 100644 --- a/tools/eslint/node_modules/doctrine/README.md +++ b/tools/eslint/node_modules/doctrine/README.md @@ -1,29 +1,54 @@ -doctrine ([doctrine](http://github.com/Constellation/doctrine)) is JSDoc parser. +[![NPM version][npm-image]][npm-url] +[![build status][travis-image]][travis-url] +[![Test coverage][coveralls-image]][coveralls-url] +[![Downloads][downloads-image]][downloads-url] +[](https://gitter.im/eslint/doctrine?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -[](https://travis-ci.org/Constellation/doctrine) -[](https://coveralls.io/r/Constellation/doctrine?branch=master) -[](https://david-dm.org/Constellation/doctrine) -[](https://david-dm.org/Constellation/doctrine#info=devDependencies) -[](https://gitter.im/Constellation/doctrine) +# Doctrine -It is now used by content assist system of [Eclipse Orion](http://www.eclipse.org/orion/) ([detail](http://planetorion.org/news/2012/10/orion-1-0-release/)). And used as JSDoc validator in [ESLint](http://eslint.org/). +Doctrine is a [JSDoc](http://usejsdoc.org) parser that parses documentation comments from JavaScript (you need to pass in the comment, not a whole JavaScript file). -Doctrine can be used in a web browser with using browserify. -or in a Node.js application via the package manager: +## Installation - npm install doctrine +You can install Doctrine using [npm](https://npmjs.com): -simple example: +``` +$ npm install doctrine --save-dev +``` + +Doctrine can also be used in web browsers using [Browserify](http://browserify.org). + +## Usage + +Require doctrine inside of your JavaScript: + +```js +var doctrine = require("doctrine"); +``` - doctrine.parse( - [ - "/**", - " * This function comment is parsed by doctrine", - " * @param {{ok:String}} userName", - "*/" - ].join('\n'), { unwrap: true }); +### parse() -and gets following information +The primary method is `parse()`, which accepts two arguments: the JSDoc comment to parse and an optional options object. The available options are: + +* `unwrap` - set to `true` to delete the leading `/**`, any `*` that begins a line, and the trailing `*/` from the source text. Default: `false`. +* `tags` - an array of tags to return. When specified, Doctrine returns only tags in this array. For example, if `tags` is `["param"]`, then only `@param` tags will be returned. Default: `null`. +* `recoverable` - set to `true` to keep parsing even when syntax errors occur. Default: `false`. +* `sloppy` - set to `true` to allow optional parameters to be specified in brackets (`@param {string} [foo]`). Default: `false`. +* `lineNumberes` - set to `true` to add `lineNumber` to each node, specifying the line on which the node is found in the source. Default: `false`. + +Here's a simple example: + +```js +var ast = doctrine.parse( + [ + "/**", + " * This function comment is parsed by doctrine", + " * @param {{ok:String}} userName", + "*/" + ].join('\n'), { unwrap: true }); +``` + +This example returns the following AST: { "description": "This function comment is parsed by doctrine", @@ -49,65 +74,24 @@ and gets following information ] } -see [demo page](http://constellation.github.com/doctrine/demo/index.html) more detail. - -### Options - -#### doctrine.parse -We can pass options to `doctrine.parse(comment, options)`. -```js -{ - unwrap: boolean, // default: false - tags: [ string ] | null, // default: null - recoverable: boolean, // default: false - sloppy: boolean, // default: false - lineNumbers: boolean // default: false -} -``` - -##### unwrap - -When `unwrap` is `true`, doctrine attempt to unwrap comment specific string from a provided comment text. (removes `/**`, `*/` and `*`) -For example, `unwrap` transforms -``` -/** - * @param use - */ -``` -to -``` -@param use -``` -If a provided comment has these comment specific strings, you need to specify this `unwrap` option to `true`. +See the [demo page](http://eslint.org/doctrine/demo/) more detail. -##### tags +## Team -When `tags` array is specified, doctrine only produce tags that is specified in this array. -For example, if you specify `[ 'param' ]`, doctrine only produces `param` tags. -If null is specified, doctrine produces all tags that doctrine can recognize. +These folks keep the project moving and are resources for help: -##### recoverable +* Nicholas C. Zakas ([@nzakas](https://github.com/nzakas)) - project lead +* Yusuke Suzuki ([@constellation](https://github.com/constellation)) - reviewer -When `recoverable` is `true`, doctrine becomes `recoverable` - When failing to parse jsdoc comment, doctrine recovers its state and attempt to continue parsing. +## Contributing -##### sloppy +Issues and pull requests will be triaged and responded to as quickly as possible. We operate under the [ESLint Contributor Guidelines](http://eslint.org/docs/developer-guide/contributing), so please be sure to read them before contributing. If you're not sure where to dig in, check out the [issues](https://github.com/eslint/doctrine/issues). -When `sloppy` is `true`, -``` -@param String [foo] -``` -'s `[foo]` is interpreted as a optional parameter, not interpreted as a name of this `@param`. +## Frequently Asked Questions -##### lineNumbers +### Can I pass a whole JavaScript file to Doctrine? -When `lineNumbers` is `true`, parsed tags will include a `lineNumber` property indicating the line (relative to the start of the comment block) where each tag is located in the source. So, given the following comment: -``` -/** - * @param {String} foo - * @return {number} - */ -``` -The `@param` tag will have `lineNumber: 1`, and the `@return` tag will have `lineNumber: 2`. +No. Doctrine can only parse JSDoc comments, so you'll need to pass just the JSDoc comment to Doctrine in order to work. ### License @@ -174,3 +158,17 @@ some of extensions is derived from closure-compiler Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ + + +### Where to ask for help? + +Join our [Chatroom](https://gitter.im/eslint/doctrine) + +[npm-image]: https://img.shields.io/npm/v/doctrine.svg?style=flat-square +[npm-url]: https://www.npmjs.com/package/doctrine +[travis-image]: https://img.shields.io/travis/eslint/doctrine/master.svg?style=flat-square +[travis-url]: https://travis-ci.org/eslint/doctrine +[coveralls-image]: https://img.shields.io/coveralls/eslint/doctrine/master.svg?style=flat-square +[coveralls-url]: https://coveralls.io/r/eslint/doctrine?branch=master +[downloads-image]: http://img.shields.io/npm/dm/doctrine.svg?style=flat-square +[downloads-url]: https://www.npmjs.com/package/doctrine |