node_modules/comment-parser/README.md - devtools/devtools-frontend - Git at Google

 # 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

 ```sh
 npm install comment-parser
 ```

 > 💡 Check out the [Playground](https://syavorsky.github.io/comment-parser)

 > 💡 Previous version lives in [0.x](https://github.com/syavorsky/comment-parser/tree/0.x) branch

 Lib mainly provides two pieces [Parser](#Parser) and [Stringifier](#Stringifier).

 ## Parser

 Let's go over string parsing:

 ```js
 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](src/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

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

 ### Description

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

 ### Tags

 ```js
  * @param {string} name the name parameter
 ```

 ```js
  * @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](https://syavorsky.github.io/comment-parser)

 ```js
 [{
   // 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

 ```ts
 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](https://syavorsky.github.io/comment-parser/#parse-defaults)
 - [line numbers control](https://syavorsky.github.io/comment-parser/#parse-line-numbering)
 - [description spacing](https://syavorsky.github.io/comment-parser/#parse-spacing)
 - [escaping](https://syavorsky.github.io/comment-parser/#parse-escaping)
 - [explore the origin source](https://syavorsky.github.io/comment-parser/#parse-source-exploration)

 [suggest more examples](https://github.com/syavorsky/comment-parser/issues/new?title=example+suggestion%3A+...&labels=example,parser)

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

 ```js
 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

 ```js
 /**
  * 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](https://syavorsky.github.io/comment-parser/#stringify-formatting)

 [suggest more examples](https://github.com/syavorsky/comment-parser/issues/new?title=example+suggestion%3A+...&labels=example,stringifier)

 ## Migrating from 0.x version

 Code of pre-1.0 version is forked into [0.x](https://github.com/syavorsky/comment-parser/tree/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](migrate-1.0.md).
	# 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

	```sh
	npm install comment-parser
	```

	> 💡 Check out the [Playground](https://syavorsky.github.io/comment-parser)

	> 💡 Previous version lives in [0.x](https://github.com/syavorsky/comment-parser/tree/0.x) branch

	Lib mainly provides two pieces [Parser](#Parser) and [Stringifier](#Stringifier).

	## Parser

	Let's go over string parsing:

	```js
	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](src/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

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

	### Description

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

	### Tags

	```js
	* @param {string} name the name parameter
	```

	```js
	* @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](https://syavorsky.github.io/comment-parser)

	```js
	[{
	// 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

	```ts
	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](https://syavorsky.github.io/comment-parser/#parse-defaults)
	- [line numbers control](https://syavorsky.github.io/comment-parser/#parse-line-numbering)
	- [description spacing](https://syavorsky.github.io/comment-parser/#parse-spacing)
	- [escaping](https://syavorsky.github.io/comment-parser/#parse-escaping)
	- [explore the origin source](https://syavorsky.github.io/comment-parser/#parse-source-exploration)

	[suggest more examples](https://github.com/syavorsky/comment-parser/issues/new?title=example+suggestion%3A+...&labels=example,parser)

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

	```js
	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

	```js
	/**
	* 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](https://syavorsky.github.io/comment-parser/#stringify-formatting)

	[suggest more examples](https://github.com/syavorsky/comment-parser/issues/new?title=example+suggestion%3A+...&labels=example,stringifier)

	## Migrating from 0.x version

	Code of pre-1.0 version is forked into [0.x](https://github.com/syavorsky/comment-parser/tree/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](migrate-1.0.md).