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