Spaces:
Runtime error
Runtime error
| [![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) | |
| # Doctrine | |
| 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). | |
| ## Installation | |
| You can install Doctrine using [npm](https://npmjs.com): | |
| ``` | |
| $ 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"); | |
| ``` | |
| ### parse() | |
| 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`. | |
| * `lineNumbers` - set to `true` to add `lineNumber` to each node, specifying the line on which the node is found in the source. Default: `false`. | |
| * `range` - set to `true` to add `range` to each node, specifying the start and end index of the node in the original comment. 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", | |
| "tags": [ | |
| { | |
| "title": "param", | |
| "description": null, | |
| "type": { | |
| "type": "RecordType", | |
| "fields": [ | |
| { | |
| "type": "FieldType", | |
| "key": "ok", | |
| "value": { | |
| "type": "NameExpression", | |
| "name": "String" | |
| } | |
| } | |
| ] | |
| }, | |
| "name": "userName" | |
| } | |
| ] | |
| } | |
| See the [demo page](http://eslint.org/doctrine/demo/) more detail. | |
| ## Team | |
| These folks keep the project moving and are resources for help: | |
| * Nicholas C. Zakas ([@nzakas](https://github.com/nzakas)) - project lead | |
| * Yusuke Suzuki ([@constellation](https://github.com/constellation)) - reviewer | |
| ## Contributing | |
| 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). | |
| ## Frequently Asked Questions | |
| ### Can I pass a whole JavaScript file to Doctrine? | |
| No. Doctrine can only parse JSDoc comments, so you'll need to pass just the JSDoc comment to Doctrine in order to work. | |
| ### License | |
| #### doctrine | |
| Copyright JS Foundation and other contributors, https://js.foundation | |
| Licensed under the Apache License, Version 2.0 (the "License"); | |
| you may not use this file except in compliance with the License. | |
| You may obtain a copy of the License at | |
| http://www.apache.org/licenses/LICENSE-2.0 | |
| Unless required by applicable law or agreed to in writing, software | |
| distributed under the License is distributed on an "AS IS" BASIS, | |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| See the License for the specific language governing permissions and | |
| limitations under the License. | |
| #### esprima | |
| some of functions is derived from esprima | |
| Copyright (C) 2012, 2011 [Ariya Hidayat](http://ariya.ofilabs.com/about) | |
| (twitter: [@ariyahidayat](http://twitter.com/ariyahidayat)) and other contributors. | |
| Redistribution and use in source and binary forms, with or without | |
| modification, are permitted provided that the following conditions are met: | |
| * Redistributions of source code must retain the above copyright | |
| notice, this list of conditions and the following disclaimer. | |
| * Redistributions in binary form must reproduce the above copyright | |
| notice, this list of conditions and the following disclaimer in the | |
| documentation and/or other materials provided with the distribution. | |
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | |
| AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
| IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
| ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY | |
| DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES | |
| (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | |
| LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND | |
| ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
| (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | |
| THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
| #### closure-compiler | |
| 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 | |