Skip to content

Parse JavaScript code comments. Works with block and line comments, and should work with CSS, LESS, SASS, or any language with the same comment formats.

License

Notifications You must be signed in to change notification settings

jonschlinkert/parse-comments

Repository files navigation

parse-comments NPM version NPM monthly downloads NPM total downloads Linux Build Status

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\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

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
Building 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

Contributors

Commits Contributor
35 jonschlinkert
4 doowb

Author

Jon Schlinkert

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.

About

Parse JavaScript code comments. Works with block and line comments, and should work with CSS, LESS, SASS, or any language with the same comment formats.

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project

 

Packages

No packages published