parse-comments

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

Install with npm:

$ npm install --save parse-comments

Usage

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: []
  }
]

API

Comments

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 function
• returns {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 function
• returns {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 middleware
• fn {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 middleware
• fn {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 javascript
• options {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 javascript
• options {Object}
• returns {Array}: Array of objects.

Example

const parser = new ParseComments();
const comments = parser.parse(string);

Params

• str {String}: JavaScript comment
• options {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 test

(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

Contributors

| Commits | Contributor |
| --- | --- |
| 35 | jonschlinkert |
| 4 | doowb |

Author

Jon Schlinkert

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

License

Copyright © 2018, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.8.0, on November 24, 2018.