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 :heart: and support.
Install with npm:
$ npm install --save parse-comments
const 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
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}: The node.type
to 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, if type
is 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, if type
is 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 with description
string, array of examples
, array of tags
(strings), and a footer
if 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 objectExample
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 test
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.