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();

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

<summary>Building docs</summary>

(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

License

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

Current Tags

1.0.0 ... latest (6 years ago)

parse-comments

Install

Usage

API

Comments

Contributors

Author

License

Current Tags

13 Versions