1[![NPM version][npm-image]][npm-url] 2[![build status][travis-image]][travis-url] 3[![Test coverage][coveralls-image]][coveralls-url] 4[![Downloads][downloads-image]][downloads-url] 5[![Join the chat at https://gitter.im/eslint/doctrine](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/eslint/doctrine?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 6 7# Doctrine 8 9Doctrine 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). 10 11## Installation 12 13You can install Doctrine using [npm](https://npmjs.com): 14 15``` 16$ npm install doctrine --save-dev 17``` 18 19Doctrine can also be used in web browsers using [Browserify](http://browserify.org). 20 21## Usage 22 23Require doctrine inside of your JavaScript: 24 25```js 26var doctrine = require("doctrine"); 27``` 28 29### parse() 30 31The primary method is `parse()`, which accepts two arguments: the JSDoc comment to parse and an optional options object. The available options are: 32 33* `unwrap` - set to `true` to delete the leading `/**`, any `*` that begins a line, and the trailing `*/` from the source text. Default: `false`. 34* `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`. 35* `recoverable` - set to `true` to keep parsing even when syntax errors occur. Default: `false`. 36* `sloppy` - set to `true` to allow optional parameters to be specified in brackets (`@param {string} [foo]`). Default: `false`. 37* `lineNumbers` - set to `true` to add `lineNumber` to each node, specifying the line on which the node is found in the source. Default: `false`. 38 39Here's a simple example: 40 41```js 42var ast = doctrine.parse( 43 [ 44 "/**", 45 " * This function comment is parsed by doctrine", 46 " * @param {{ok:String}} userName", 47 "*/" 48 ].join('\n'), { unwrap: true }); 49``` 50 51This example returns the following AST: 52 53 { 54 "description": "This function comment is parsed by doctrine", 55 "tags": [ 56 { 57 "title": "param", 58 "description": null, 59 "type": { 60 "type": "RecordType", 61 "fields": [ 62 { 63 "type": "FieldType", 64 "key": "ok", 65 "value": { 66 "type": "NameExpression", 67 "name": "String" 68 } 69 } 70 ] 71 }, 72 "name": "userName" 73 } 74 ] 75 } 76 77See the [demo page](http://eslint.org/doctrine/demo/) more detail. 78 79## Team 80 81These folks keep the project moving and are resources for help: 82 83* Nicholas C. Zakas ([@nzakas](https://github.com/nzakas)) - project lead 84* Yusuke Suzuki ([@constellation](https://github.com/constellation)) - reviewer 85 86## Contributing 87 88Issues 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). 89 90## Frequently Asked Questions 91 92### Can I pass a whole JavaScript file to Doctrine? 93 94No. Doctrine can only parse JSDoc comments, so you'll need to pass just the JSDoc comment to Doctrine in order to work. 95 96 97### License 98 99#### doctrine 100 101Copyright (C) 2012 [Yusuke Suzuki](http://github.com/Constellation) 102 (twitter: [@Constellation](http://twitter.com/Constellation)) and other contributors. 103 104Redistribution and use in source and binary forms, with or without 105modification, are permitted provided that the following conditions are met: 106 107 * Redistributions of source code must retain the above copyright 108 notice, this list of conditions and the following disclaimer. 109 110 * Redistributions in binary form must reproduce the above copyright 111 notice, this list of conditions and the following disclaimer in the 112 documentation and/or other materials provided with the distribution. 113 114THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 115AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 116IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 117ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY 118DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 119(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 120LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 121ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 122(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 123THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 124 125#### esprima 126 127some of functions is derived from esprima 128 129Copyright (C) 2012, 2011 [Ariya Hidayat](http://ariya.ofilabs.com/about) 130 (twitter: [@ariyahidayat](http://twitter.com/ariyahidayat)) and other contributors. 131 132Redistribution and use in source and binary forms, with or without 133modification, are permitted provided that the following conditions are met: 134 135 * Redistributions of source code must retain the above copyright 136 notice, this list of conditions and the following disclaimer. 137 138 * Redistributions in binary form must reproduce the above copyright 139 notice, this list of conditions and the following disclaimer in the 140 documentation and/or other materials provided with the distribution. 141 142THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 143AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 144IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 145ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY 146DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 147(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 148LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 149ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 150(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 151THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 152 153 154#### closure-compiler 155 156some of extensions is derived from closure-compiler 157 158Apache License 159Version 2.0, January 2004 160http://www.apache.org/licenses/ 161 162 163### Where to ask for help? 164 165Join our [Chatroom](https://gitter.im/eslint/doctrine) 166 167[npm-image]: https://img.shields.io/npm/v/doctrine.svg?style=flat-square 168[npm-url]: https://www.npmjs.com/package/doctrine 169[travis-image]: https://img.shields.io/travis/eslint/doctrine/master.svg?style=flat-square 170[travis-url]: https://travis-ci.org/eslint/doctrine 171[coveralls-image]: https://img.shields.io/coveralls/eslint/doctrine/master.svg?style=flat-square 172[coveralls-url]: https://coveralls.io/r/eslint/doctrine?branch=master 173[downloads-image]: http://img.shields.io/npm/dm/doctrine.svg?style=flat-square 174[downloads-url]: https://www.npmjs.com/package/doctrine 175