Notify President Madagascar

    parse-comments

    1.0.0 • Public • Published

    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

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

    Install

    npm i parse-comments

    DownloadsWeekly Downloads

    2,430

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    90.6 kB

    Total Files

    28

    Last publish

    Collaborators

    • doowb
    • jonschlinkert