1 | # comment-parser
|
2 |
|
3 | `comment-parser` is a library helping to handle Generic JSDoc-style comments. It is
|
4 |
|
5 | - **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.
|
6 | - **no dependencies** – it is compact and environment-agnostic, can be run on both the server and browser sides
|
7 | - **highly customizable** – with a little code you can deeply customize how comments are parsed
|
8 | - **bidirectional** - you can write comment blocks back to the source after updating or formatting
|
9 | - **strictly typed** - comes with generated `d.ts` data definitions since written in TypeScript
|
10 |
|
11 | ```sh
|
12 | npm install comment-parser
|
13 | ```
|
14 |
|
15 | > 💡 Check out the [Playground](https://syavorsky.github.io/comment-parser)
|
16 |
|
17 | > 💡 Previous version lives in [0.x](https://github.com/syavorsky/comment-parser/tree/0.x) branch
|
18 |
|
19 | Lib mainly provides two pieces [Parser](#Parser) and [Stringifier](#Stringifier).
|
20 |
|
21 | ## Parser
|
22 |
|
23 | Let's go over string parsing:
|
24 |
|
25 | ```js
|
26 | const { parse } = require('comment-parser/lib')
|
27 |
|
28 | const source = `
|
29 | /**
|
30 | * Description may go
|
31 | * over few lines followed by @tags
|
32 | * @param {string} name the name parameter
|
33 | * @param {any} value the value of any type
|
34 | */`
|
35 |
|
36 | const parsed = parse(source)
|
37 | ```
|
38 |
|
39 | 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)
|
40 |
|
41 | The input source is first parsed into lines, then lines split into tokens, and finally, tokens are processed into blocks of tags
|
42 |
|
43 | ### Block
|
44 |
|
45 | ```js
|
46 | /**
|
47 | * Description may go
|
48 | * over multiple lines followed by @tags
|
49 | * @param {string} name the name parameter
|
50 | * @param {any} value the value parameter
|
51 | */
|
52 | ```
|
53 |
|
54 | ### Description
|
55 |
|
56 | ```js
|
57 | /**
|
58 | * Description may go
|
59 | * over multiple lines followed by @tags
|
60 | ```
|
61 |
|
62 | ### Tags
|
63 |
|
64 | ```js
|
65 | * @param {string} name the name parameter
|
66 | ```
|
67 |
|
68 | ```js
|
69 | * @param {any} value the value parameter
|
70 | */
|
71 | ```
|
72 |
|
73 | ### Tokens
|
74 |
|
75 | ```
|
76 | |line|start|delimiter|postDelimiter|tag |postTag|name |postName|type |postType|description |end|
|
77 | |----|-----|---------|-------------|------|-------|-----|--------|--------|--------|--------------------------------|---|
|
78 | | 0|{2} |/** | | | | | | | | | |
|
79 | | 1|{3} |* |{1} | | | | | | |Description may go | |
|
80 | | 2|{3} |* |{1} | | | | | | |over few lines followed by @tags| |
|
81 | | 3|{3} |* |{1} |@param|{1} |name |{1} |{string}|{1} |the name parameter | |
|
82 | | 4|{3} |* |{1} |@param|{1} |value|{1} |{any} |{1} |the value of any type | |
|
83 | | 5|{3} | | | | | | | | | |*/ |
|
84 | ```
|
85 |
|
86 | ### Result
|
87 |
|
88 | The result is an array of Block objects, see the full output on the [playground](https://syavorsky.github.io/comment-parser)
|
89 |
|
90 | ```js
|
91 | [{
|
92 | // uppper text of the comment, overall block description
|
93 | description: 'Description may go over multiple lines followed by @tags',
|
94 | // list of block tags: @param, @param
|
95 | tags: [{
|
96 | // tokens.tag without "@"
|
97 | tag: 'param',
|
98 | // unwrapped tokens.name
|
99 | name: 'name',
|
100 | // unwrapped tokens.type
|
101 | type: 'string',
|
102 | // true, if tokens.name is [optional]
|
103 | optional: false,
|
104 | // default value if optional [name=default] has one
|
105 | default: undefined,
|
106 | // tokens.description assembled from a siongle or multiple lines
|
107 | description: 'the name parameter',
|
108 | // problems occured while parsing this tag section, subset of ../problems array
|
109 | problems: [],
|
110 | // source lines processed for extracting this tag, "slice" of the ../source item reference
|
111 | source: [ ... ],
|
112 | }, ... ],
|
113 | // source is an array of `Line` items having the source
|
114 | // line number and `Tokens` that can be assembled back into
|
115 | // the line string preserving original formatting
|
116 | source: [{
|
117 | // source line number
|
118 | number: 1,
|
119 | // source line string
|
120 | source: "/**",
|
121 | // source line tokens
|
122 | tokens: {
|
123 | // indentation
|
124 | start: "",
|
125 | // delimiter, either '/**', '*/', '*', or ''. Mid lines may have no delimiters
|
126 | delimiter: "/**",
|
127 | // space between delimiter and tag
|
128 | postDelimiter: "",
|
129 | // tag starting with "@"
|
130 | tag: "",
|
131 | // space between tag and type
|
132 | postTag: "",
|
133 | // name with no whitespaces or "multiple words" wrapped into quotes. May occure in [name] and [name=default] forms
|
134 | name: "",
|
135 | // space between name and type
|
136 | postName: "",
|
137 | // type is has to be {wrapped} into curlies otherwise will be omitted
|
138 | type: "",
|
139 | // space between type and description
|
140 | postType: "",
|
141 | // description is basicaly rest of the line
|
142 | description: "",
|
143 | // closing */ marker if present
|
144 | end: ""
|
145 | }
|
146 | }, ... ],
|
147 | // problems occured while parsing the block
|
148 | problems: [],
|
149 | }];
|
150 | ```
|
151 |
|
152 | While `.source[].tokens` are not providing readable annotation information, they are essential for tracing data origins and assembling string blocks with `stringify`
|
153 |
|
154 | ### options
|
155 |
|
156 | ```ts
|
157 | interface Options {
|
158 | // start count for source line numbers
|
159 | startLine: number;
|
160 | // escaping chars sequence marking wrapped content literal for the parser
|
161 | fence: string;
|
162 | // block and comment description compaction strategy
|
163 | spacing: 'compact' | 'preserve';
|
164 | // tokenizer functions extracting name, type, and description out of tag, see Tokenizer
|
165 | tokenizers: Tokenizer[];
|
166 | }
|
167 | ```
|
168 |
|
169 | examples
|
170 | - [default config](https://syavorsky.github.io/comment-parser/#parse-defaults)
|
171 | - [line numbers control](https://syavorsky.github.io/comment-parser/#parse-line-numbering)
|
172 | - [description spacing](https://syavorsky.github.io/comment-parser/#parse-spacing)
|
173 | - [escaping](https://syavorsky.github.io/comment-parser/#parse-escaping)
|
174 | - [explore the origin source](https://syavorsky.github.io/comment-parser/#parse-source-exploration)
|
175 |
|
176 | [suggest more examples](https://github.com/syavorsky/comment-parser/issues/new?title=example+suggestion%3A+...&labels=example,parser)
|
177 |
|
178 | ## Stringifier
|
179 |
|
180 | 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.
|
181 |
|
182 | ```js
|
183 | const { parse, stringify, transforms: {flow, align, indent} } = require('comment-parser');
|
184 |
|
185 | const source = `
|
186 | /**
|
187 | * Description may go
|
188 | * over multiple lines followed by @tags
|
189 | *
|
190 | * @my-tag {my.type} my-name description line 1
|
191 | description line 2
|
192 | * description line 3
|
193 | */`;
|
194 |
|
195 | const parsed = parse(source);
|
196 | const transform = flow(align(), indent(0))
|
197 | console.log(stringify(transform(parsed[0])));
|
198 | ```
|
199 |
|
200 | ### Result
|
201 |
|
202 | ```js
|
203 | /**
|
204 | * Description may go
|
205 | * over multiple lines followed by @tags
|
206 | *
|
207 | * @my-tag {my.type} my-name description line 1
|
208 | description line 2
|
209 | * description line 3
|
210 | */
|
211 | ```
|
212 |
|
213 | examples
|
214 | - [format comments](https://syavorsky.github.io/comment-parser/#stringify-formatting)
|
215 |
|
216 | [suggest more examples](https://github.com/syavorsky/comment-parser/issues/new?title=example+suggestion%3A+...&labels=example,stringifier)
|
217 |
|
218 | ## Migrating from 0.x version
|
219 |
|
220 | 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).
|