--- /dev/null
+[![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
projects / dotfiles / .git / blobdiff