comment-parser
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.4 • Public • Published

    comment-parser

    comment-parser is a library helping to handle Generic JSDoc-style comments. It is

    • language-agnostic – no semantics enforced. You decide what tags are and what they mean. And it can be used with any language supporting /** */ source comments.
    • no dependencies – it is compact and environment-agnostic, can be run on both the server and browser sides
    • highly customizable – with a little code you can deeply customize how comments are parsed
    • bidirectional - you can write comment blocks back to the source after updating or formatting
    • strictly typed - comes with generated d.ts data definitions since written in TypeScript
    npm install comment-parser

    💡 Check out the Playground

    💡 Previous version lives in 0.x branch

    Lib mainly provides two pieces Parser and Stringifier.

    Parser

    Let's go over string parsing:

    const { parse } = require('comment-parser/lib')
    
    const source = `
    /**
     * Description may go
     * over few lines followed by @tags
     * @param {string} name the name parameter
     * @param {any} value the value of any type
     */`
    
    const parsed = parse(source)

    Lib source code is written in TypeScript and all data shapes are conveniently available for your IDE of choice. All types described below can be found in primitives.ts

    The input source is first parsed into lines, then lines split into tokens, and finally, tokens are processed into blocks of tags

    Block

    /**
     * Description may go
     * over multiple lines followed by @tags
     * @param {string} name the name parameter
     * @param {any} value the value parameter
     */

    Description

    /**
     * Description may go
     * over multiple lines followed by @tags

    Tags

     * @param {string} name the name parameter
     * @param {any} value the value parameter
     */

    Tokens

    |line|start|delimiter|postDelimiter|tag   |postTag|name |postName|type    |postType|description                     |end|
    |----|-----|---------|-------------|------|-------|-----|--------|--------|--------|--------------------------------|---|
    |   0|{2}  |/**      |             |      |       |     |        |        |        |                                |   |
    |   1|{3}  |*        |{1}          |      |       |     |        |        |        |Description may go              |   |
    |   2|{3}  |*        |{1}          |      |       |     |        |        |        |over few lines followed by @tags|   |
    |   3|{3}  |*        |{1}          |@param|{1}    |name |{1}     |{string}|{1}     |the name parameter              |   |
    |   4|{3}  |*        |{1}          |@param|{1}    |value|{1}     |{any}   |{1}     |the value of any type           |   |
    |   5|{3}  |         |             |      |       |     |        |        |        |                                |*/ |
    

    Result

    The result is an array of Block objects, see the full output on the playground

    [{
      // uppper text of the comment, overall block description
      description: 'Description may go over multiple lines followed by @tags',
      // list of block tags: @param, @param
      tags: [{
        // tokens.tag without "@"
        tag: 'param',
        // unwrapped tokens.name
        name: 'name',
        // unwrapped tokens.type
        type: 'string',
        // true, if tokens.name is [optional]
        optional: false,
        // default value if optional [name=default] has one
        default: undefined,
        // tokens.description assembled from a siongle or multiple lines
        description: 'the name parameter',
        // problems occured while parsing this tag section, subset of ../problems array
        problems: [],
        // source lines processed for extracting this tag, "slice" of the ../source item reference
        source: [ ... ],
      }, ... ],
      // source is an array of `Line` items having the source
      // line number and `Tokens` that can be assembled back into
      // the line string preserving original formatting
      source: [{
        // source line number
        number: 1,
        // source line string
        source: "/**",
        // source line tokens
        tokens: {
          // indentation
          start: "",
          // delimiter, either '/**', '*/', '*', or ''. Mid lines may have no delimiters
          delimiter: "/**",
          // space between delimiter and tag
          postDelimiter: "",
          // tag starting with "@"
          tag: "",
          // space between tag and type
          postTag: "",
          // name with no whitespaces or "multiple words" wrapped into quotes. May occure in [name] and [name=default] forms
          name: "",
          // space between name and type
          postName: "",
          // type is has to be {wrapped} into curlies otherwise will be omitted
          type: "",
          // space between type and description
          postType: "",
          // description is basicaly rest of the line
          description: "",
          // closing */ marker if present
          end: ""
        }
      }, ... ],
      // problems occured while parsing the block
      problems: [],
    }];

    While .source[].tokens are not providing readable annotation information, they are essential for tracing data origins and assembling string blocks with stringify

    options

    interface Options {
      // start count for source line numbers
      startLine: number;
      // escaping chars sequence marking wrapped content literal for the parser
      fence: string;
      // block and comment description compaction strategy
      spacing: 'compact' | 'preserve';
      // tokenizer functions extracting name, type, and description out of tag, see Tokenizer
      tokenizers: Tokenizer[];
    }

    examples

    suggest more examples

    Stringifier

    The stringifier is an important piece used by other tools updating the source code. It goes over Block.source[].tokens items and assembles them back to the string. It might be used with various transforms applied before stringifying.

    const { parse, stringify, transforms: {flow, align, indent} } = require('comment-parser');
    
    const source = `
      /**
       * Description may go
       * over multiple lines followed by @tags
       *
    * @my-tag {my.type} my-name description line 1
          description line 2
        * description line 3
       */`;
    
    const parsed = parse(source);
    const transform = flow(align(), indent(0))
    console.log(stringify(transform(parsed[0])));

    Result

    /**
     * Description may go
     * over multiple lines followed by @tags
     *
     * @my-tag {my.type} my-name description line 1
                                 description line 2
     *                           description line 3
     */

    examples

    suggest more examples

    Migrating from 0.x version

    Code of pre-1.0 version is forked into 0.x and will phase out eventually. Please file the issue if you find some previously existing functionality can't be achieved with 1.x API. Check out migration notes.

    Install

    npm i comment-parser

    DownloadsWeekly Downloads

    1,004,435

    Version

    1.2.4

    License

    MIT

    Unpacked Size

    356 kB

    Total Files

    148

    Last publish

    Collaborators

    • yavorskiys