comment-parser

What is comment-parser?

The comment-parser npm package is a tool designed to parse comments from source code files into a structured format. It primarily focuses on extracting JSDoc-like comment blocks and converting them into a JSON object, making it easier to analyze and manipulate documentation embedded within code.

What are comment-parser's main functionalities?

Parsing JSDoc comments

This feature allows the extraction of JSDoc comments from a string of source code. The output is an array of objects, each representing a parsed comment block with details about parameters, return types, and descriptions.

const parse = require('comment-parser');
const sourceCode = `/**
 * This is a description of the function
 * @param {string} name - The name of the person
 * @return {string} - Greeting message
 */
function greet(name) { return 'Hello ' + name; }`;
const parsedComments = parse(sourceCode);
console.log(parsedComments);

Custom tags parsing

This feature supports parsing custom tags within comments. Users can configure the parser to handle specific tag formats and preserve spacing, allowing for more flexible documentation styles.

const parse = require('comment-parser');
const options = { dotted_names: false, spacing: 'preserve' };
const sourceCode = `/**
 * @customTag Here is some custom information
 */`;
const parsedComments = parse(sourceCode, options);
console.log(parsedComments);

Other packages similar to comment-parser

jsdoc

JSDoc is a popular tool similar to comment-parser but with a broader scope. It not only parses comments but also generates entire websites of documentation from the parsed data. JSDoc supports a wide range of tags and offers more extensive configuration options compared to comment-parser.

doctrine

Doctrine is another npm package that parses JSDoc comments. It is somewhat similar to comment-parser but focuses more on the syntactic structure of the comments rather than converting them into a structured format. Doctrine is often used for linting tools and other development utilities.

README

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

• default config
• line numbers control
• description spacing
• escaping
• explore the origin source

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

• format comments

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.

Changelog

v1.1.0

• split tokenizers into separate modules
• allow multiline {type} definitions - issue #109
• allow using "=>" in [name=default] defaults – issue #112
• allow using "=" in quoted [name=default] defaults – issue #112
• add tokenizers usage example - issue #111