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 ❤️ 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\[email protected] {String} options\[email protected] 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

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Contributors

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.