comment-parser 1.1.1 → 1.1.2

package/browser/index.js

@@ -200,7 +200,7 @@ var CommentParser = (function (exports) {
                     tokens.type = tokens.postDelimiter.slice(offset) + type;
                     tokens.postDelimiter = tokens.postDelimiter.slice(0, offset);
                 }
-                [tokens.postType, tokens.description] = splitSpace(tokens.description.slice(tokens.type.length));
+                [tokens.postType, tokens.description] = splitSpace(tokens.description.slice(type.length));
                 parts.push(tokens.type);
             }
             parts[0] = parts[0].slice(1);
@@ -430,14 +430,6 @@ var CommentParser = (function (exports) {
         type: Math.max(w.type, t.type.length),
         name: Math.max(w.name, t.name.length),
     });
-    //  /**
-    //   * 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 space = (len) => ''.padStart(len, ' ');
     function align() {
         let intoTags = false;
@@ -463,14 +455,41 @@ var CommentParser = (function (exports) {
                     tokens.start = space(w.start + 1);
                     break;
                 default:
-                    tokens.start = space(w.start + 3);
                     tokens.delimiter = '';
+                    tokens.start = space(w.start + 2); // compensate delimiter
             }
-            if (intoTags) {
+            if (!intoTags) {
+                tokens.postDelimiter = tokens.description === '' ? '' : ' ';
+                return Object.assign(Object.assign({}, line), { tokens });
+            }
+            const nothingAfter = {
+                delim: false,
+                tag: false,
+                type: false,
+                name: false,
+            };
+            if (tokens.description === '') {
+                nothingAfter.name = true;
+                tokens.postName = '';
+                if (tokens.name === '') {
+                    nothingAfter.type = true;
+                    tokens.postType = '';
+                    if (tokens.type === '') {
+                        nothingAfter.tag = true;
+                        tokens.postTag = '';
+                        if (tokens.tag === '') {
+                            nothingAfter.delim = true;
+                        }
+                    }
+                }
+            }
+            tokens.postDelimiter = nothingAfter.delim ? '' : ' ';
+            if (!nothingAfter.tag)
                 tokens.postTag = space(w.tag - tokens.tag.length + 1);
+            if (!nothingAfter.type)
                 tokens.postType = space(w.type - tokens.type.length + 1);
+            if (!nothingAfter.name)
                 tokens.postName = space(w.name - tokens.name.length + 1);
-            }
             return Object.assign(Object.assign({}, line), { tokens });
         }
         return (_a) => {

package/es6/index.d.ts

@@ -7,7 +7,7 @@ import alignTransform from './transforms/align';
 import indentTransform from './transforms/indent';
 import { flow as flowTransform } from './transforms/index';
 export declare function parse(source: string, options?: Partial<ParserOptions>): import("./primitives").Block[];
-export declare const stringify: (block: import("./primitives").Block) => string;
+export declare const stringify: import("./stringifier").Stringifier;
 export { default as inspect } from './stringifier/inspect';
 export declare const transforms: {
     flow: typeof flowTransform;

package/es6/parser/index.d.ts

@@ -6,4 +6,5 @@ export interface Options {
     spacing: 'compact' | 'preserve';
     tokenizers: Tokenizer[];
 }
-export default function getParser({ startLine, fence, spacing, tokenizers, }?: Partial<Options>): (source: string) => Block[];
+export declare type Parser = (source: string) => Block[];
+export default function getParser({ startLine, fence, spacing, tokenizers, }?: Partial<Options>): Parser;

package/es6/parser/tokenizers/type.js

@@ -47,7 +47,7 @@ export default function typeTokenizer(spacing = 'compact') {
                 tokens.type = tokens.postDelimiter.slice(offset) + type;
                 tokens.postDelimiter = tokens.postDelimiter.slice(0, offset);
             }
-            [tokens.postType, tokens.description] = splitSpace(tokens.description.slice(tokens.type.length));
+            [tokens.postType, tokens.description] = splitSpace(tokens.description.slice(type.length));
             parts.push(tokens.type);
         }
         parts[0] = parts[0].slice(1);

package/es6/stringifier/index.d.ts

@@ -1,2 +1,3 @@
 import { Block } from '../primitives';
-export default function getStringifier(): (block: Block) => string;
+export declare type Stringifier = (block: Block) => string;
+export default function getStringifier(): Stringifier;

package/es6/transforms/align.js

@@ -23,14 +23,6 @@ const getWidth = (w, { tokens: t }) => ({
     type: Math.max(w.type, t.type.length),
     name: Math.max(w.name, t.name.length),
 });
-//  /**
-//   * 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 space = (len) => ''.padStart(len, ' ');
 export default function align() {
     let intoTags = false;
@@ -56,14 +48,41 @@ export default function align() {
                 tokens.start = space(w.start + 1);
                 break;
             default:
-                tokens.start = space(w.start + 3);
                 tokens.delimiter = '';
+                tokens.start = space(w.start + 2); // compensate delimiter
         }
-        if (intoTags) {
+        if (!intoTags) {
+            tokens.postDelimiter = tokens.description === '' ? '' : ' ';
+            return Object.assign(Object.assign({}, line), { tokens });
+        }
+        const nothingAfter = {
+            delim: false,
+            tag: false,
+            type: false,
+            name: false,
+        };
+        if (tokens.description === '') {
+            nothingAfter.name = true;
+            tokens.postName = '';
+            if (tokens.name === '') {
+                nothingAfter.type = true;
+                tokens.postType = '';
+                if (tokens.type === '') {
+                    nothingAfter.tag = true;
+                    tokens.postTag = '';
+                    if (tokens.tag === '') {
+                        nothingAfter.delim = true;
+                    }
+                }
+            }
+        }
+        tokens.postDelimiter = nothingAfter.delim ? '' : ' ';
+        if (!nothingAfter.tag)
             tokens.postTag = space(w.tag - tokens.tag.length + 1);
+        if (!nothingAfter.type)
             tokens.postType = space(w.type - tokens.type.length + 1);
+        if (!nothingAfter.name)
             tokens.postName = space(w.name - tokens.name.length + 1);
-        }
         return Object.assign(Object.assign({}, line), { tokens });
     }
     return (_a) => {

package/lib/index.d.ts

@@ -7,7 +7,7 @@ import alignTransform from './transforms/align';
 import indentTransform from './transforms/indent';
 import { flow as flowTransform } from './transforms/index';
 export declare function parse(source: string, options?: Partial<ParserOptions>): import("./primitives").Block[];
-export declare const stringify: (block: import("./primitives").Block) => string;
+export declare const stringify: import("./stringifier").Stringifier;
 export { default as inspect } from './stringifier/inspect';
 export declare const transforms: {
     flow: typeof flowTransform;

package/lib/parser/index.d.ts

@@ -6,4 +6,5 @@ export interface Options {
     spacing: 'compact' | 'preserve';
     tokenizers: Tokenizer[];
 }
-export default function getParser({ startLine, fence, spacing, tokenizers, }?: Partial<Options>): (source: string) => Block[];
+export declare type Parser = (source: string) => Block[];
+export default function getParser({ startLine, fence, spacing, tokenizers, }?: Partial<Options>): Parser;

package/lib/parser/tokenizers/type.js

@@ -49,7 +49,7 @@ function typeTokenizer(spacing = 'compact') {
                 tokens.type = tokens.postDelimiter.slice(offset) + type;
                 tokens.postDelimiter = tokens.postDelimiter.slice(0, offset);
             }
-            [tokens.postType, tokens.description] = util_1.splitSpace(tokens.description.slice(tokens.type.length));
+            [tokens.postType, tokens.description] = util_1.splitSpace(tokens.description.slice(type.length));
             parts.push(tokens.type);
         }
         parts[0] = parts[0].slice(1);

package/lib/stringifier/index.d.ts

@@ -1,2 +1,3 @@
 import { Block } from '../primitives';
-export default function getStringifier(): (block: Block) => string;
+export declare type Stringifier = (block: Block) => string;
+export default function getStringifier(): Stringifier;

package/lib/transforms/align.js

@@ -25,14 +25,6 @@ const getWidth = (w, { tokens: t }) => ({
     type: Math.max(w.type, t.type.length),
     name: Math.max(w.name, t.name.length),
 });
-//  /**
-//   * 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 space = (len) => ''.padStart(len, ' ');
 function align() {
     let intoTags = false;
@@ -58,14 +50,41 @@ function align() {
                 tokens.start = space(w.start + 1);
                 break;
             default:
-                tokens.start = space(w.start + 3);
                 tokens.delimiter = '';
+                tokens.start = space(w.start + 2); // compensate delimiter
         }
-        if (intoTags) {
+        if (!intoTags) {
+            tokens.postDelimiter = tokens.description === '' ? '' : ' ';
+            return Object.assign(Object.assign({}, line), { tokens });
+        }
+        const nothingAfter = {
+            delim: false,
+            tag: false,
+            type: false,
+            name: false,
+        };
+        if (tokens.description === '') {
+            nothingAfter.name = true;
+            tokens.postName = '';
+            if (tokens.name === '') {
+                nothingAfter.type = true;
+                tokens.postType = '';
+                if (tokens.type === '') {
+                    nothingAfter.tag = true;
+                    tokens.postTag = '';
+                    if (tokens.tag === '') {
+                        nothingAfter.delim = true;
+                    }
+                }
+            }
+        }
+        tokens.postDelimiter = nothingAfter.delim ? '' : ' ';
+        if (!nothingAfter.tag)
             tokens.postTag = space(w.tag - tokens.tag.length + 1);
+        if (!nothingAfter.type)
             tokens.postType = space(w.type - tokens.type.length + 1);
+        if (!nothingAfter.name)
             tokens.postName = space(w.name - tokens.name.length + 1);
-        }
         return Object.assign(Object.assign({}, line), { tokens });
     }
     return (_a) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-parser",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Generic JSDoc-like comment parser",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/parser/index.ts

@@ -22,6 +22,8 @@ export interface Options {
   tokenizers: Tokenizer[];
 }
 
+export type Parser = (source: string) => Block[];
+
 export default function getParser({
   startLine = 0,
   fence = '```',
@@ -32,7 +34,7 @@ export default function getParser({
     tokenizeName(),
     tokenizeDescription(spacing),
   ],
-}: Partial<Options> = {}) {
+}: Partial<Options> = {}): Parser {
   if (startLine < 0 || startLine % 1 > 0) throw new Error('Invalid startLine');
 
   const parseSource = sourceParser({ startLine });

package/src/parser/tokenizers/type.ts

@@ -71,7 +71,7 @@ export default function typeTokenizer(spacing: Spacing = 'compact'): Tokenizer {
         tokens.postDelimiter = tokens.postDelimiter.slice(0, offset);
       }
       [tokens.postType, tokens.description] = splitSpace(
-        tokens.description.slice(tokens.type.length)
+        tokens.description.slice(type.length)
       );
       parts.push(tokens.type);
     }

package/src/stringifier/index.ts

@@ -1,5 +1,7 @@
 import { Block, Tokens } from '../primitives';
 
+export type Stringifier = (block: Block) => string;
+
 function join(tokens: Tokens): string {
   return (
     tokens.start +
@@ -16,7 +18,7 @@ function join(tokens: Tokens): string {
   );
 }
 
-export default function getStringifier() {
+export default function getStringifier(): Stringifier {
   return (block: Block): string =>
     block.source.map(({ tokens }) => join(tokens)).join('\n');
 }

package/src/transforms/align.ts

@@ -23,15 +23,6 @@ const getWidth = (w: Width, { tokens: t }: Line) => ({
   name: Math.max(w.name, t.name.length),
 });
 
-//  /**
-//   * 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 space = (len: number) => ''.padStart(len, ' ');
 
 export default function align(): Transform {
@@ -62,15 +53,49 @@ export default function align(): Transform {
         tokens.start = space(w.start + 1);
         break;
       default:
-        tokens.start = space(w.start + 3);
         tokens.delimiter = '';
+        tokens.start = space(w.start + 2); // compensate delimiter
+    }
+
+    if (!intoTags) {
+      tokens.postDelimiter = tokens.description === '' ? '' : ' ';
+      return { ...line, tokens };
+    }
+
+    const nothingAfter = {
+      delim: false,
+      tag: false,
+      type: false,
+      name: false,
+    };
+
+    if (tokens.description === '') {
+      nothingAfter.name = true;
+      tokens.postName = '';
+
+      if (tokens.name === '') {
+        nothingAfter.type = true;
+        tokens.postType = '';
+
+        if (tokens.type === '') {
+          nothingAfter.tag = true;
+          tokens.postTag = '';
+
+          if (tokens.tag === '') {
+            nothingAfter.delim = true;
+          }
+        }
+      }
     }
 
-    if (intoTags) {
+    tokens.postDelimiter = nothingAfter.delim ? '' : ' ';
+
+    if (!nothingAfter.tag)
       tokens.postTag = space(w.tag - tokens.tag.length + 1);
+    if (!nothingAfter.type)
       tokens.postType = space(w.type - tokens.type.length + 1);
+    if (!nothingAfter.name)
       tokens.postName = space(w.name - tokens.name.length + 1);
-    }
 
     return { ...line, tokens };
   }

package/tests/e2e/examples.js

@@ -161,9 +161,9 @@ function parse_source_exploration(source, parse, stringify, transforms) {
 }
 
 function parse_advanced_parsing(source, parse, _, _, tokenizers) {
-  // Each '@tag ...' section results into Spec. Spec is computed by
-  // the chain of tokenizers each contributing change to the Spec.* and Spec.tags[].tokens.
-  // Default parse() options come with stadart tokenizers
+  // Each '@tag ...' section results into a Spec. The Spec is computed by
+  // the chain of tokenizers each contributing a change to the the Spec.* and the Spec.tags[].tokens.
+  // Default parse() options come with stadart tokenizers:
   // {
   //   ...,
   //   spacing = 'compact',

package/tests/e2e/issue-119.spec.js

@@ -0,0 +1,29 @@
+const {
+  parse,
+  stringify,
+  transforms: { align },
+} = require('../../lib');
+
+test('align - ignore trailing right space', () => {
+  const source = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     * @param {string} name
+     * @param {any} value the value parameter
+     */`;
+
+  const expected = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     * @param {string} name
+     * @param {any}    value the value parameter
+     */`.slice(1);
+
+  const parsed = parse(source);
+  const aligned = align()(parsed[0]);
+  const stringified = stringify(aligned);
+
+  expect(stringified).toEqual(expected);
+});

package/tests/e2e/issue-120.spec.js

@@ -0,0 +1,29 @@
+const {
+  parse,
+  stringify,
+  transforms: { align },
+} = require('../../lib');
+
+test('align - collapse postDelim', () => {
+  const source = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     *        @param {string} name the name parameter
+     * @param {any} value the value parameter
+     */`.slice(1);
+
+  const expected = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     * @param {string} name  the name parameter
+     * @param {any}    value the value parameter
+     */`.slice(1);
+
+  const parsed = parse(source);
+  const aligned = align()(parsed[0]);
+  const stringified = stringify(aligned);
+
+  expect(stringified).toEqual(expected);
+});

package/tests/e2e/issue-121.spec.js

@@ -0,0 +1,102 @@
+const { parse, inspect } = require('../../lib');
+
+test('name cut off', () => {
+  const source = `
+    /**
+     * @param {{includeWhiteSpace: (boolean|undefined),
+     *    ignoreElementOrder: (boolean|undefined)}} [options] The options.
+     */`.slice(1);
+
+  const tagSource = [
+    {
+      number: 1,
+      source: '     * @param {{includeWhiteSpace: (boolean|undefined),',
+      tokens: {
+        start: '     ',
+        delimiter: '*',
+        postDelimiter: ' ',
+        tag: '@param',
+        postTag: ' ',
+        type: '{{includeWhiteSpace: (boolean|undefined),',
+        postType: '',
+        name: '',
+        postName: '',
+        description: '',
+        end: '',
+      },
+    },
+    {
+      number: 2,
+      source:
+        '     *    ignoreElementOrder: (boolean|undefined)}} [options] The options.',
+      tokens: {
+        start: '     ',
+        delimiter: '*',
+        postDelimiter: ' ',
+        tag: '',
+        postTag: '',
+        type: '   ignoreElementOrder: (boolean|undefined)}}',
+        postType: ' ',
+        name: '[options]',
+        postName: ' ',
+        description: 'The options.',
+        end: '',
+      },
+    },
+    {
+      number: 3,
+      source: '     */',
+      tokens: {
+        start: '     ',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        type: '',
+        postType: '',
+        name: '',
+        postName: '',
+        description: '',
+        end: '*/',
+      },
+    },
+  ];
+
+  const parsed = parse(source);
+  // console.log(inspect(parsed[0]));
+
+  expect(parsed[0]).toMatchObject({
+    problems: [],
+    tags: [
+      {
+        tag: 'param',
+        type:
+          '{includeWhiteSpace: (boolean|undefined),ignoreElementOrder: (boolean|undefined)}',
+        name: 'options',
+        optional: true,
+        description: 'The options.',
+        source: tagSource,
+      },
+    ],
+    source: [
+      {
+        number: 0,
+        source: '    /**',
+        tokens: {
+          start: '    ',
+          delimiter: '/**',
+          postDelimiter: '',
+          tag: '',
+          postTag: '',
+          type: '',
+          postType: '',
+          name: '',
+          postName: '',
+          description: '',
+          end: '',
+        },
+      },
+      ...tagSource,
+    ],
+  });
+});

package/tests/unit/spec-type-tokenizer.spec.ts

@@ -137,7 +137,7 @@ test('omit', () => {
   );
 });
 
-test('multiline - preserve', () => {
+test('multiline', () => {
   const spec = seedSpec({
     source: [
       {
@@ -152,23 +152,16 @@ test('multiline - preserve', () => {
         source: '...',
         tokens: seedTokens({
           postDelimiter: '  ',
-          description: 'number',
+          description: 'number)} function type',
         }),
       },
       {
         number: 3,
         source: '...',
-        tokens: seedTokens({
-          description: ')} function type',
-        }),
-      },
-      {
-        number: 4,
-        source: '...',
         tokens: seedTokens(),
       },
       {
-        number: 5,
+        number: 4,
         source: '...',
         tokens: seedTokens({
           end: '*/',
@@ -192,25 +185,18 @@ test('multiline - preserve', () => {
         number: 2,
         source: '...',
         tokens: seedTokens({
-          type: '  number',
-        }),
-      },
-      {
-        number: 3,
-        source: '...',
-        tokens: seedTokens({
-          type: ')}',
+          type: '  number)}',
           postType: ' ',
           description: 'function type',
         }),
       },
       {
-        number: 4,
+        number: 3,
         source: '...',
         tokens: seedTokens(),
       },
       {
-        number: 5,
+        number: 4,
         source: '...',
         tokens: seedTokens({
           end: '*/',

package/tests/unit/transforms-align.spec.ts

@@ -1,6 +1,14 @@
 import align from '../../src/transforms/align';
-import getParser from '../../src/parser/index';
-import getStringifier from '../../src/stringifier/index';
+import getParser, { Parser } from '../../src/parser/index';
+import getStringifier, { Stringifier } from '../../src/stringifier/index';
+
+let parse: Parser;
+let stringify: Stringifier;
+
+beforeEach(() => {
+  parse = getParser();
+  stringify = getStringifier();
+});
 
 test('multiline', () => {
   const source = `
@@ -23,18 +31,20 @@ test('multiline', () => {
    * @another-tag {another-type} another-name description line 1
                                               description line 2
    *                                          description line 3
-   */`;
+   */`.slice(1);
 
-  const parsed = getParser()(source);
-  const out = getStringifier()(align()(parsed[0]));
+  const parsed = parse(source);
+  const aligned = align()(parsed[0]);
+  const out = stringify(aligned);
 
-  expect(out).toBe(expected.slice(1));
+  // console.log(inspect(aligned));
+  expect(out).toBe(expected);
 });
 
 test('one-liner', () => {
   const source = `  /** @tag {type} name description */`;
-  const parsed = getParser()(source);
-  const out = getStringifier()(align()(parsed[0]));
+  const parsed = parse(source);
+  const out = stringify(align()(parsed[0]));
 
   expect(out).toBe(source);
 });
@@ -43,8 +53,8 @@ test('same line open', () => {
   const source = `
   /** @tag {type} name description
    */`.slice(1);
-  const parsed = getParser()(source);
-  const out = getStringifier()(align()(parsed[0]));
+  const parsed = parse(source);
+  const out = stringify(align()(parsed[0]));
 
   expect(out).toBe(source);
 });
@@ -52,22 +62,76 @@ test('same line open', () => {
 test('same line close', () => {
   const source = `
   /** 
+   * @tag {type} name description */`;
+
+  const expected = `
+  /**
    * @tag {type} name description */`.slice(1);
-  const parsed = getParser()(source);
-  const out = getStringifier()(align()(parsed[0]));
 
-  expect(out).toBe(source);
+  const parsed = parse(source);
+  const aligned = align()(parsed[0]);
+  const out = stringify(aligned);
+
+  expect(out).toBe(expected);
 });
 
 test('spec source referencing', () => {
-  const parsed = getParser()(`/** @tag {type} name Description */`);
+  const parsed = parse(`/** @tag {type} name Description */`);
   const block = align()(parsed[0]);
   expect(block.tags[0].source[0] === block.source[0]).toBe(true);
 });
 
 test('block source clonning', () => {
-  const parsed = getParser()(`/** @tag {type} name Description */`);
+  const parsed = parse(`/** @tag {type} name Description */`);
   const block = align()(parsed[0]);
   parsed[0].source[0].tokens.description = 'test';
   expect(block.source[0].tokens.description).toBe('Description ');
 });
+
+test('ignore right whitespace', () => {
+  const source = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     * @param {string} name
+     * @param {any} value the value parameter
+     */`.slice(1);
+
+  const expected = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     * @param {string} name
+     * @param {any}    value the value parameter
+     */`.slice(1);
+
+  const parsed = parse(source);
+  const aligned = align()(parsed[0]);
+  const stringified = stringify(aligned);
+
+  expect(stringified).toEqual(expected);
+});
+
+test('collapse postDelimiter', () => {
+  const source = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     *  @param {string} name the name parameter
+     *     @param {any} value the value parameter
+     */`.slice(1);
+
+  const expected = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     * @param {string} name  the name parameter
+     * @param {any}    value the value parameter
+     */`.slice(1);
+
+  const parsed = parse(source);
+  const aligned = align()(parsed[0]);
+  const stringified = stringify(aligned);
+
+  expect(stringified).toEqual(expected);
+});