comment-parser 1.0.0-beta.2 → 1.1.1

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# 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
+
+# v1.1.1
+- add helpers for rewiring Spec.source <-> Spec.tags.source
+
+# v1.0.0
+- complete rewrite in TS with more flexible API
+
 # v0.7.6
 - distinct non-critical errors by providing `err.warning`
 

package/README.md

@@ -2,9 +2,9 @@
 
 `comment-parser` is a library helping to handle Generic JSDoc-style comments. It is
 
-- **language-agnostic** – no semantic enforced. You may use it anywhere as long as `/** */` comments are supported.
-- **no dependencies** – it is compact and environment-agnostic, can be ran on both server and browser sides
-- **highly customizable** – with a little of code you can deeply customize how comments are parsed
+- **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
 
@@ -12,23 +12,25 @@
 npm install comment-parser
 ```
 
-### 💡 Check out the [Playground](https://syavorsky.github.io/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
 
-Lets go over string parsing
+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 name {string} name parameter
- * @param value {any} value of any type
+ * @param {string} name the name parameter
+ * @param {any} value the value of any type
  */`
 
 const parsed = parse(source)
@@ -36,11 +38,11 @@ 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 fist parsed into lines, then lines split into tokens, and finally, tokens are processed into blocks of tags
+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
@@ -51,7 +53,7 @@ The input source is fist parsed into lines, then lines split into tokens, and fi
 
 ### Description
 
-```
+```js
 /**
  * Description may go
  * over multiple lines followed by @tags
@@ -59,11 +61,11 @@ The input source is fist parsed into lines, then lines split into tokens, and fi
 
 ### Tags
 
-```
+```js
  * @param {string} name the name parameter
 ```
 
-```
+```js
  * @param {any} value the value parameter
  */
 ```
@@ -71,7 +73,14 @@ The input source is fist parsed into lines, then lines split into tokens, and fi
 ### Tokens
 
 ```
-| ... | * | ... | @param | ... | value | ... | {any} | ... | value of any type
+|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
@@ -150,14 +159,14 @@ interface Options {
   startLine: number;
   // escaping chars sequence marking wrapped content literal for the parser
   fence: string;
-  // block and comment description compaction strategy, see Spacer
-  spacing: 'compact' | 'preserve' | Spacer;
+  // block and comment description compaction strategy
+  spacing: 'compact' | 'preserve';
   // tokenizer functions extracting name, type, and description out of tag, see Tokenizer
   tokenizers: Tokenizer[];
 }
 ```
 
-examples 
+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)
@@ -168,16 +177,16 @@ examples
 
 ## Stringifier
 
-The stringifier is an important piece used by other tools updating the source code. It goes over `Block.source[].tokens` and assembles them back to a string. It might be used with various transforms applied to the parsed data before stringifying.
+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('./lib/');
+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
@@ -190,7 +199,7 @@ console.log(stringify(transform(parsed[0])));
 
 ### Result
 
-```
+```js
 /**
  * Description may go
  * over multiple lines followed by @tags