Parse code comments from JavaScript or any language that uses the same format.
Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.
Install with npm:
$ npm install --save parse-commentsconst Comments = require('parse-comments');
const comments = new Comments();
const ast = comments.parse(str);
console.log(ast);Parses a comment like this:
/**
* Create an instance of `CustomClass` with the given `options`.
*
* @param {String} options
* @api public
*/
class CustomClass {
constructor(options) {
this.options = options;
}
set(type, fn) {
// do stuff
}
}Into an array of comment objects, like this:
[
{
type: 'BlockComment',
value: '\nCreate an instance of `CustomClass` with the given `options`.\n\n@param {String} options\n@api public',
range: [0, 117],
loc: { start: { line: 1, column: 0 }, end: { line: 6, column: 3 } },
codeStart: 119,
raw:
'*\n * Create an instance of `CustomClass` with the given `options`.\n *\n * @param {String} options\n * @api public\n ',
code: {
context: {
type: 'class',
ctor: 'CustomClass',
name: 'CustomClass',
extends: undefined,
string: 'new CustomClass()'
},
value: 'class CustomClass {',
range: [119, 138],
loc: { start: { line: 8, column: 0 }, end: { line: 8, column: 19 } }
},
description: 'Create an instance of `CustomClass` with the given `options`.',
footer: '',
examples: [],
tags: [
{
title: 'param',
name: 'options',
description: '',
type: { type: 'NameExpression', name: 'String' }
},
{ title: 'api', name: 'public', description: '' }
],
inlineTags: []
}
]Create an instance of Comments with the given options.
Params
- {Object}: options
Example
const Comments = require('parse-comments');
const comments = new Comments();Register a parser function of the given type
Params
type{string|object}fn{Function}returns{Object}
Params
fn{Function}: plugin functionreturns{Object}: Returns the comments instance for chaining.
Example
// plugin example
function yourPlugin(options) {
return function(comments) {
// do stuff
};
}
// usage
comments.use(yourPlugin());Params
type{String}: Thenode.typeto call the handler on. You can override built-in middleware by registering a handler of the same name, or register a handler for rendering a new type.fn{Function}: The handler functionreturns{Object}: Returns the instance for chaining.
Example
comments.set('param', function(node) {
// do stuff to node
});Params
type{String|Object|Array}: Handler name(s), or an object of middlewarefn{Function}: Handler function, iftypeis a string or array. Otherwise this argument is ignored.returns{Object}: Returns the instance for chaining.
Example
comments.before('param', function(node) {
// do stuff to node
});
// or
comments.before(['param', 'returns'], function(node) {
// do stuff to node
});
// or
comments.before({
param: function(node) {
// do stuff to node
},
returns: function(node) {
// do stuff to node
}
});Params
type{String|Object|Array}: Handler name(s), or an object of middlewarefn{Function}: Handler function, iftypeis a string or array. Otherwise this argument is ignored.returns{Object}: Returns the instance for chaining.
Example
comments.after('param', function(node) {
// do stuff to node
});
// or
comments.after(['param', 'returns'], function(node) {
// do stuff to node
});
// or
comments.after({
param: function(node) {
// do stuff to node
},
returns: function(node) {
// do stuff to node
}
});Params
javascript{String}: String of javascriptoptions{Object}returns{Object}: Returns an object withdescriptionstring, array ofexamples, array oftags(strings), and afooterif descriptions are defined both before and after tags.
Example
const parser = new ParseComments();
const tokens = parser.tokenize([string]);Params
str{String}: String of javascriptoptions{Object}returns{Array}: Array of objects.
Example
const parser = new ParseComments();
const comments = parser.parse(string);Params
str{String}: JavaScript commentoptions{Object}returns{Object}: Parsed comment object
Example
let parser = new ParseComments();
let comments = parser.parseComment(string);**Params**
* **{}**: {String}
* **{String}**: name
* **{String}**: name The name to use for foo ```
* **{Object}**: tok Takes a token from
* `returns` **{Object}**
```js
**Params**
* **{}**: {String}
* **{String}**: name
* **{String}**: name The name to use for foo ```
* **{Object}**: tok
* `returns` **{Object}**
```js
**Params**
* **{}**: {String}
* **{}**: {...string}
* **{}**: {function(...a)}
* **{}**: {function(...a:b)}
* **{}**: {String|Array}
* **{}**: {(String|Array)}
* **{}**: {{foo: bar}}
* **{}**: {String[]}
* ``` **{Array<String|Function|Array>=}**
* **{String}**: value The
* `returns` **{Object}**
```js
**Params**
* **{}**: {String}
* **{}**: {String|Array}
* **{}**: {(String|Array)}
* **{}**: {{foo: bar}} ```
* **{string}**: str The string to parse
* `returns` **{object}**
Returns true if the given `comment` is valid. By default, comments
are considered valid when they begin with `/**`, and do not contain
`jslint`, `jshint`, `eshint`, or `eslint`. A custom `isValid` function may be
passed on the constructor options.
**Params**
* `comment` **{Object}**
* `options` **{Object}**
* `returns` **{Boolean}**
## About
<details>
<summary><strong>Contributing</strong></summary>
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.
</details>
<details>
<summary><strong>Running Tests</strong></summary>
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
```sh
$ npm install && npm testBuilding docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb#dev verb-generate-readme && verb| Commits | Contributor |
|---|---|
| 35 | jonschlinkert |
| 4 | doowb |
Jon Schlinkert
Copyright © 2018, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.8.0, on November 24, 2018.