comment-parser 0.2.4 → 0.4.0

package/tests/parse.spec.js

@@ -2,78 +2,71 @@ var fs = require('fs');
 var expect = require('chai').expect;
 var parse = require('../index');
 
-describe('Single comment string parsing', function() {
+describe('Comment string parsing', function() {
+
+  /**
+   * Source lines numeration:
+   *
+   * 0 function() {
+   * 1  // source with comments
+   * 2 }
+   * 
+   */
 
   function parsed(func, opts) {
     var str = func.toString();
     return parse(str.slice(
       str.indexOf('{') + 1,
       str.lastIndexOf('}')
-    ).trim(), opts);
+    ), opts);
   }
 
-  it('should parse one-liner doc block', function() {
-    expect(parsed(function(){
-      /** Description */
-      var a;
-    })[0].description)
-      .to.eq('Description');
-  });
-
-  it('should gracefully parse one-liner with tag', function() {
-    var p = parsed(function(){
-      /** @tag */
-      var a;
-    });
-
-    expect(p[0].description)
-      .to.eq('');
-
-    expect(p[0].line)
-      .to.eq(0);
-
-    expect(p[0].tags.length)
-      .to.eq(1);
-
-    expect(p[0].tags[0].tag)
-      .to.eq('tag');
-
-    expect(p[0].tags[0].line)
-      .to.eq(0);
-  });
-
-  it('should parse simple doc block with description', function() {
+  it('should parse doc block with description', function() {
     expect(parsed(function(){
       /**
        * Description
        */
-    })[0].description)
-      .to.eq('Description');
+    })[0])
+      .to.eql({
+        description : 'Description',
+        source      : 'Description',
+        line        : 1,
+        tags        : []
+      });
   });
 
-  it('should split the description', function() {
+  it('should skip surrounding empty lines while preserving line numbers', function() {
     expect(parsed(function(){
       /**
+       *
+       * 
        * Description first line
        *
        * Description second line
+       * 
        */
       var a;
-    })[0].description)
-      .to.eq('Description first line\n\nDescription second line');
+    })[0])
+      .eql({
+        description : 'Description first line\n\nDescription second line',
+        source      : 'Description first line\n\nDescription second line',
+        line        : 1,
+        tags        : []
+      });
   });
 
-  it('should keep description "" if omitted', function() {
+  it('should skip empty blocks', function() {
+
     expect(parsed(function(){
       /**
-       *
+       * 
        */
       var a;
-    })[0].description)
-      .to.eq('');
+    }).length)
+      .to.eq(0);
   });
 
-  it('should parse multiple comments', function() {
+  it('should parse multiple doc blocks', function() {
     var p = parsed(function(){
       /**
        * Description first line
@@ -89,14 +82,37 @@ describe('Single comment string parsing', function() {
     expect(p.length)
       .to.eq(2);
 
-    expect(p[0].description)
-      .to.eq('Description first line');
+    expect(p[0])
+      .to.eql({
+        description : 'Description first line',
+        source      : 'Description first line',
+        line        : 1,
+        tags        : []
+      });
+
+    expect(p[1])
+      .to.eql({
+        description : 'Description second line',
+        source      : 'Description second line',
+        line        : 6,
+        tags        : []
+      });
+  });
 
-    expect(p[1].description)
-      .to.eq('Description second line');
+  it('should parse one line block', function() {
+    expect(parsed(function(){
+      /** Description */
+      var a;
+    })[0])
+      .to.eql({
+        description : 'Description',
+        source      : 'Description',
+        line        : 1,
+        tags        : []
+      });
   });
 
-  it('should return `null` for `/* */` comments', function() {
+  it('should skip `/* */` comments', function() {
     expect(parsed(function(){
       /*
        *
@@ -106,7 +122,7 @@ describe('Single comment string parsing', function() {
       .to.eq(0);
   });
 
-  it('should return `null` for `/*** */` comments', function() {
+  it('should skip `/*** */` comments', function() {
     expect(parsed(function(){
       /*
        *
@@ -116,21 +132,68 @@ describe('Single comment string parsing', function() {
       .to.eq(0);
   });
 
+  it('should preserve empty lines and indentation with `opts.trim = false`', function() {
+    expect(parsed(function(){
+      /**
+       *
+       * 
+       *   Description first line
+       *     second line
+       * 
+       *       third line
+       */
+      var a;
+    }, {
+      trim: false
+    })[0])
+      .eql({
+        description : '\n\n\n  Description first line\n    second line\n\n      third line\n',
+        source      : '\n\n\n  Description first line\n    second line\n\n      third line\n',
+        line        : 1,
+        tags        : []
+      });
+  });
+
+  it('should parse one line block with tag', function() {
+    expect(parsed(function(){
+      /** @tag */
+      var a;
+    })[0])
+      .to.eql({
+        description : '',
+        line        : 1,
+        source      : '@tag',
+        tags        : [{
+          tag         : 'tag',
+          type        : '',
+          name        : '',
+          description : '',
+          line        : 1,
+          optional    : false,
+          source      : '@tag'
+        }]
+      });
+  });
+
   it('should parse `@tag`', function() {
       expect(parsed(function(){
         /**
+         * 
          * @my-tag
          */
         var a;
       })[0])
         .to.eql({
-          line        : 0,
+          line        : 1,
+          source      : '@my-tag',
           description : '',
           tags: [{
-            line        : 1,
+            line        : 3,
             tag         : 'my-tag',
+            source      : '@my-tag',
             type        : '',
             name        : '',
+            optional    : false,
             description : ''
           }]
         });
@@ -144,164 +207,218 @@ describe('Single comment string parsing', function() {
         var a;
       })[0])
         .to.eql({
-          line        : 0,
+          line        : 1,
+          source      : '@my-tag {my.type}',
           description : '',
           tags: [{
-            line        : 1,
+            line        : 2,
             tag         : 'my-tag',
             type        : 'my.type',
             name        : '',
+            source      : '@my-tag {my.type}',
+            optional    : false,
             description : ''
           }]
         });
   });
 
-  it('should parse `@tag {my.type} name`', function() {
+  it('should parse tag with name only `@tag name`', function() {
       expect(parsed(function(){
         /**
-         * @my-tag {my.type} name
+         * @my-tag name
          */
-        var a;
       })[0])
         .to.eql({
-          line        : 0,
+          line        : 1,
           description : '',
+          source      : '@my-tag name',
           tags: [{
+            line        : 2,
             tag         : 'my-tag',
-            line        : 1,
-            type        : 'my.type',
+            type        : '',
             name        : 'name',
+            source      : '@my-tag name',
+            optional    : false,
             description : ''
           }]
         });
   });
 
-  it('should parse `@tag name`', function() {
+  it('should parse tag with type and name `@tag {my.type} name`', function() {
       expect(parsed(function(){
         /**
-         * @my-tag name
+         * @my-tag {my.type} name
          */
       })[0])
         .to.eql({
-          line        : 0,
+          line        : 1,
+          source      : '@my-tag {my.type} name',    
           description : '',
           tags: [{
-            line        : 1,
             tag         : 'my-tag',
-            type        : '',
+            line        : 2,
+            type        : 'my.type',
             name        : 'name',
-            description : ''
+            source      : '@my-tag {my.type} name',    
+            description : '',
+            optional    : false
           }]
         });
   });
 
-  it('should parse multiline tags', function() {
-    var p = parsed(function(){
-      /**
-       * @example
-       * // here is example
-       * call('value');
-       */
-      var a;
-    });
-
-    expect(p[0].line)
-      .to.eq(0);
-
-    expect(p[0].tags.length)
-      .to.eq(1);
-
-    expect(p[0].tags[0].tag)
-      .to.eq('example');
-
-    expect(p[0].tags[0].line)
-      .to.eq(1);
-
-    expect(p[0].tags[0].name)
-      .to.eq('');
+  it('should parse tag with type, name and description `@tag {my.type} name description`', function() {
+      expect(parsed(function(){
+        /**
+         * @my-tag {my.type} name description
+         */
+      })[0])
+        .to.eql({
+          line        : 1,
+          source      : '@my-tag {my.type} name description',
+          description : '',
+          tags: [{
+            tag         : 'my-tag',
+            line        : 2,
+            type        : 'my.type',
+            name        : 'name',
+            source      : '@my-tag {my.type} name description',    
+            description : 'description',
+            optional    : false
+          }]
+        });
+  });
 
-    expect(p[0].tags[0].description)
-      .to.eq('// here is example\ncall(\'value\');');
+  it('should parse tag with multiline description', function() {
+      expect(parsed(function(){
+        /**
+         * @my-tag {my.type} name description line 1
+         * description line 2
+         * description line 3
+         */
+      })[0])
+        .to.eql({
+          line        : 1,
+          source      : '@my-tag {my.type} name description line 1\ndescription line 2\ndescription line 3',
+          description : '',
+          tags: [{
+            tag         : 'my-tag',
+            line        : 2,
+            type        : 'my.type',
+            name        : 'name',
+            source      : '@my-tag {my.type} name description line 1\ndescription line 2\ndescription line 3',
+            description : 'description line 1\ndescription line 2\ndescription line 3',
+            optional    : false
+          }]
+        });
   });
 
-  it('should parse `@tag {my.type} [name]`', function() {
+  it('should parse tag with type and optional name `@tag {my.type} [name]`', function() {
       expect(parsed(function(){
         /**
          * @my-tag {my.type} [name]
          */
       })[0])
         .to.eql({
-          line        : 0,
+          line        : 1,
           description : '',
+          source      : '@my-tag {my.type} [name]',
           tags: [{
             tag         : 'my-tag',
-            line        : 1,
+            line        : 2,
+            type        : 'my.type',
+            name        : 'name',
+            description : '',
+            source      : '@my-tag {my.type} [name]',
+            optional    : true
+          }]
+        });
+  });
+
+  it('should parse tag with type and optional name with default value `@tag {my.type} [name=value]`', function() {
+      expect(parsed(function(){
+        /**
+         * @my-tag {my.type} [name=value]
+         */
+      })[0])
+        .to.eql({
+          line        : 1,
+          description : '',
+          source      : '@my-tag {my.type} [name=value]',
+          tags: [{
+            tag         : 'my-tag',
+            line        : 2,
             type        : 'my.type',
             name        : 'name',
+            default     : 'value',
+            source      : '@my-tag {my.type} [name=value]',
             description : '',
             optional    : true
           }]
         });
   });
 
-  // http://usejsdoc.org/tags-param.html
-  it('should parse `@tag {my.type} [name=John Doe]`', function() {
+  it('should tolerate default value with whitespces `@tag {my.type} [name=John Doe]`', function() {
       expect(parsed(function(){
         /**
          * @my-tag {my.type} [name=John Doe]
          */
       })[0])
         .to.eql({
-          line        : 0,
+          line        : 1,
           description : '',
+          source      : '@my-tag {my.type} [name=John Doe]',
           tags: [{
             tag         : 'my-tag',
-            line        : 1,
+            line        : 2,
             type        : 'my.type',
             name        : 'name',
             description : '',
+            source      : '@my-tag {my.type} [name=John Doe]',
             optional    : true,
             default     : 'John Doe'
           }]
         });
   });
 
-  // https://github.com/senchalabs/jsduck/wiki/@param
-  it('should parse quoted optionals like `@tag [name="yay"] desc`', function() {
+  it('should tolerate quoted default value `@tag [name="yay!"]`', function() {
       expect(parsed(function(){
         /**
-         * @tag {t} [name="yay!"] desc
+         * @tag {t} [name="yay!"]
          */
       })[0])
         .to.eql({
-          line: 0,
+          line: 1,
+          source: '@tag {t} [name="yay!"]',
           description: '',
           tags: [{
             tag         : 'tag',
-            line        : 1,
+            line        : 2,
             type        : 't',
             name        : 'name',
+            source      : '@tag {t} [name="yay!"]',
             default     : 'yay!',
             optional    : true,
-            description : 'desc'
+            description : ''
           }]
         });
   });
 
-  it('shouldn\'t strip different quotes in `@tag [name="yay\'] desc`', function() {
+  it('should keep value as is if quotes are mismatched `@tag [name="yay\']`', function() {
       expect(parsed(function(){
         /**
          * @tag {t} [name="yay!'] desc
          */
       })[0])
         .to.eql({
-          line: 0,
+          line: 1,
           description: '',
+          source     : '@tag {t} [name="yay!\'] desc',
           tags: [{
             tag         : 'tag',
-            line        : 1,
+            line        : 2,
             type        : 't',
             name        : 'name',
+            source      : '@tag {t} [name="yay!\'] desc',
             default     : '"yay!\'',
             optional    : true,
             description : 'desc'
@@ -309,21 +426,45 @@ describe('Single comment string parsing', function() {
         });
   });
 
-  it('should parse optional names like `@tag [...name] desc`', function() {
+  it('should parse rest names `@tag ...name desc`', function() {
+      expect(parsed(function(){
+        /**
+         * @tag {t} ...name desc
+         */
+      })[0])
+        .to.eql({
+          line        : 1,
+          description : '',
+          source      : '@tag {t} ...name desc',
+          tags: [{
+            tag         : 'tag',
+            line        : 2,
+            type        : 't',
+            name        : '...name',
+            optional    : false,
+            source      : '@tag {t} ...name desc',
+            description : 'desc'
+          }]
+        });
+  });
+
+  it('should parse optional rest names `@tag [...name] desc`', function() {
       expect(parsed(function(){
         /**
          * @tag {t} [...name] desc
          */
       })[0])
         .to.eql({
-          line: 0,
-          description: '',
+          line        : 1,
+          description : '',
+          source      : '@tag {t} [...name] desc',
           tags: [{
             tag         : 'tag',
-            line        : 1,
+            line        : 2,
             type        : 't',
             name        : '...name',
             optional    : true,
+            source      : '@tag {t} [...name] desc',
             description : 'desc'
           }]
         });
@@ -340,17 +481,22 @@ describe('Single comment string parsing', function() {
         .to.eql({
           line        : 1,
           description : 'Description',
+          source      : 'Description\n@my-tag1\n@my-tag2',
           tags        : [{
             tag         : 'my-tag1',
-            line        : 2,
+            line        : 3,
             type        : '',
             name        : '',
+            optional    : false,
+            source      : '@my-tag1',
             description : ''
           }, {
             tag         : 'my-tag2',
-            line        : 3,
+            line        : 4,
             type        : '',
             name        : '',
+            optional    : false,
+            source      : '@my-tag2',
             description : ''
           }]
         });
@@ -368,23 +514,30 @@ describe('Single comment string parsing', function() {
         .to.eql({
           line        : 1,
           description : 'Description',
+          source      : "Description\n@my-tag name\n@my-tag name.sub-name\n@my-tag name.sub-name.sub-sub-name",
           tags        : [{
             tag         : 'my-tag',
-            line        : 2,
+            line        : 3,
             type        : '',
             name        : 'name',
+            source      : '@my-tag name',
+            optional    : false,
             description : '',
             tags        : [{
               tag         : 'my-tag',
-              line        : 3,
+              line        : 4,
               type        : '',
               name        : 'sub-name',
+              optional    : false,
+              source      : '@my-tag name.sub-name',
               description : '',
               tags        : [{
                 tag         : 'my-tag',
-                line        : 4,
+                line        : 5,
                 type        : '',
                 name        : 'sub-sub-name',
+                optional    : false,
+                source      : '@my-tag name.sub-name.sub-sub-name',
                 description : ''
               }]
             }]
@@ -399,13 +552,16 @@ describe('Single comment string parsing', function() {
          */
       })[0])
         .to.eql({
-          line: 0,
-          description: '',
+          line        : 1,
+          source      : '@my-tag {{a: number}} name',
+          description : '',
           tags: [{
             tag         : 'my-tag',
-            line        : 1,
+            line        : 2,
             type        : '{a: number}',
             name        : 'name',
+            source      : '@my-tag {{a: number}} name',
+            optional    : false,
             description : ''
           }]
         });
@@ -418,15 +574,18 @@ describe('Single comment string parsing', function() {
          */
       })[0])
         .to.eql({
-          line: 0,
-          description: '',
+          line        : 1,
+          description : '',
+          source      : '@my-tag {{a: number} name',
           tags: [{
             tag         : 'my-tag',
-            line        : 1,
+            line        : 2,
             type        : '',
             name        : '',
-            description : '{{a: number} name',
-            error       : 'Unpaired curly in type doc'
+            description : '',
+            source      : '@my-tag {{a: number} name',
+            optional    : false,
+            errors      : ['parse_type: Invalid `{type}`, unpaired curlies']
           }]
         });
   });