165 lines
6.5 KiB
Markdown
165 lines
6.5 KiB
Markdown
[![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
|