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
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
[{
description: 'Description may go over multiple lines followed by @tags',
tags: [{
tag: 'param',
name: 'name',
type: 'string',
optional: false,
default: undefined,
description: 'the name parameter',
problems: [],
source: [ ... ],
}, ... ],
source: [{
number: 1,
source: "/**",
tokens: {
start: "",
delimiter: "/**",
postDelimiter: "",
tag: "",
postTag: "",
name: "",
postName: "",
type: "",
postType: "",
description: "",
end: ""
}
}, ... ],
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 {
startLine: number;
fence: string;
spacing: 'compact' | 'preserve';
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
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.