comment-parser 0.5.0 → 0.5.4

package/.travis.yml

@@ -1,6 +1,10 @@
 language: node_js
 node_js:
-  - "8.5"
-  - "6.11"
-  - "4.1"
-  - "4.0"
+  - "10"
+  - "8"
+  - "6"
+branches:
+  except:
+    - /^v\d+\.\d+\.\d+$/
+git:
+  depth: 1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# v0.5.4
+- allow quoted literal names, e.g. `@tag "My Var" description`
+
+# v0.5.3
+- corrected TypeScript definitions
+
+# v0.5.2
+- added TypeScript definitions
+- removed `readable-stream` dependency
+
+# v0.5.1
+- Support for tab as separator between tag components.
+- Docs: Indicate when `optional` is `true`; `default` property
+
 # v0.5.0
 - line wrapping control with `opts.join`
 

package/README.md

@@ -17,6 +17,7 @@ It is not trying to detect relations between tags or somehow recognize their mea
  * @some-tag {Type} name.subname Singleline or multiline description text
  * @some-tag {Type} name.subname.subsubname Singleline or
  * multiline description text
+ * @some-tag {Type} [optionalName=someDefault]
  * @another-tag
  */
 ```
@@ -49,13 +50,22 @@ this would be parsed into following
     "description": "Singleline or\nmultiline description text",
     "line": 5,
     "source": "@some-tag {Type} name.subname.subsubname Singleline or\nmultiline description text"
+  }, {
+    "tag": "some-tag",
+    "type": "Type",
+    "name": "optionalName",
+    "optional": true,
+    "description": "",
+    "line": 7,
+    "default": "someDefault",
+    "source": "@some-tag {Type} [optionalName=someDefault]"
   }, {
     "tag": "another-tag",
     "name": "",
     "optional": false,
     "type": "",
     "description": "",
-    "line": 7,
+    "line": 8,
     "source": "@another-tag"
   }],
   "line": 0,
@@ -156,8 +166,6 @@ This would produce following:
 
 ## Contributors
 
-- [Alexej Yaroshevich](https://github.com/zxqfox)
-- [Evgeny Reznichenko](https://github.com/zxcabs)
-- [Jordan Harband](https://github.com/ljharb)
-- [Sergii Iavorskyi](https://github.com/yavorskiy)
-- [tengattack](https://github.com/tengattack)
+```
+> npm info --registry https://registry.npmjs.org comment-parser contributors
+```

package/index.d.ts

@@ -0,0 +1,29 @@
+// Type definitions for comment-parser
+// Project: comment-parser
+// Definitions by: Javier "Ciberman" Mora <https://github.com/jhm-ciberman/>
+
+declare namespace CommentParser {
+  export interface Comment {
+    tags: Tag[];
+    line: number;
+    description: string;
+    source: string;
+  }
+  export interface Tag {
+    tag: string;
+    name: string;
+    optional: boolean;
+    type: string;
+    description: string;
+    line: number;
+    source: string;
+  }
+  export interface Options {
+    parsers?: [(str: string, data: any) => { source: string, data: any }];
+    dotted_names?: boolean;
+  }
+}
+
+declare function parse(str: string, opts?: CommentParser.Options): [CommentParser.Comment];
+
+export = parse;

package/index.js

@@ -2,7 +2,7 @@
 'use strict'
 
 var fs = require('fs')
-var stream = require('readable-stream')
+var stream = require('stream')
 var util = require('util')
 
 var parse = require('./parser')

package/package.json

@@ -1,24 +1,23 @@
 {
   "name": "comment-parser",
-  "version": "0.5.0",
+  "version": "0.5.4",
   "description": "Generic JSDoc-like comment parser. ",
   "main": "index.js",
+  "types": "index.d.ts",
   "directories": {
     "test": "tests"
   },
-  "dependencies": {
-    "readable-stream": "^2.0.4"
-  },
+  "dependencies": {},
   "devDependencies": {
-    "chai": "~1.9.0",
+    "chai": "^4.2.0",
     "eslint": "^4.7.1",
     "eslint-config-standard": "^10.2.1",
     "eslint-plugin-import": "^2.7.0",
     "eslint-plugin-node": "^5.1.1",
     "eslint-plugin-promise": "^3.5.0",
     "eslint-plugin-standard": "^3.0.1",
-    "mocha": "^3.5.3",
-    "nodemon": "^1.2.1"
+    "mocha": "^5.2.0",
+    "nodemon": "^1.18.9"
   },
   "scripts": {
     "pretest": "eslint .",
@@ -35,6 +34,14 @@
     "parser"
   ],
   "author": "Sergii Iavorskyi <yavorskiy.s@gmail.com> (https://github.com/yavorskiy)",
+  "contributors": [
+    "Alexej Yaroshevich (https://github.com/zxqfox)",
+    "Dieter Oberkofler (https://github.com/doberkofler)",
+    "Evgeny Reznichenko (https://github.com/zxcabs)",
+    "Javier \"Ciberma\" Mora (https://github.com/jhm-ciberman)",
+    "Jordan Harband (https://github.com/ljharb)",
+    "tengattack (https://github.com/tengattack)"
+  ],
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/yavorskiy/comment-parser/issues"

package/parsers.js

@@ -1,7 +1,7 @@
 function skipws (str) {
   var i = 0
   do {
-    if (str[i] !== ' ') { return i }
+    if (str[i] !== ' ' && str[i] !== '\t') { return i }
   } while (++i < str.length)
   return i
 }
@@ -51,26 +51,35 @@ PARSERS.parse_name = function parse_name (str, data) {
   var pos = skipws(str)
   var name = ''
   var brackets = 0
+  var res = {optional: false}
+
+  // if it starts with quoted group assume it is a literal
+  var quotedGroups = str.slice(pos).split('"')
+  if (quotedGroups.length > 1 && quotedGroups[0] === '' && quotedGroups.length % 2 === 1) {
+    name = quotedGroups[1]
+    pos += name.length + 2
+  // assume name is non-space string or anything wrapped into brackets
+  } else {
+    while (pos < str.length) {
+      brackets += (str[pos] === '[' ? 1 : (str[pos] === ']' ? -1 : 0))
+      name += str[pos]
+      pos++
+      if (brackets === 0 && /\s/.test(str[pos])) { break }
+    }
 
-  while (pos < str.length) {
-    brackets += (str[pos] === '[' ? 1 : (str[pos] === ']' ? -1 : 0))
-    name += str[pos]
-    pos++
-    if (brackets === 0 && /\s/.test(str[pos])) { break }
-  }
-
-  if (brackets !== 0) { throw new Error('Invalid `name`, unpaired brackets') }
+    if (brackets !== 0) { throw new Error('Invalid `name`, unpaired brackets') }
 
-  var res = {name: name, optional: false}
+    res = {name: name, optional: false}
 
-  if (name[0] === '[' && name[name.length - 1] === ']') {
-    res.optional = true
-    name = name.slice(1, -1)
+    if (name[0] === '[' && name[name.length - 1] === ']') {
+      res.optional = true
+      name = name.slice(1, -1)
 
-    if (name.indexOf('=') !== -1) {
-      var parts = name.split('=')
-      name = parts[0]
-      res.default = parts[1].replace(/^(["'])(.+)(\1)$/, '$2')
+      if (name.indexOf('=') !== -1) {
+        var parts = name.split('=')
+        name = parts[0]
+        res.default = parts[1].replace(/^(["'])(.+)(\1)$/, '$2')
+      }
     }
   }
 

package/tests/parse.js

@@ -11,8 +11,8 @@ var parse = require('../index')
 
 module.exports = function (func, opts) {
   var str = func.toString()
-  return parse(str.slice(
-    str.indexOf('{') + 1,
-    str.lastIndexOf('}')
-  ), opts)
+  str = str
+    .slice(str.indexOf('{') + 1, str.lastIndexOf('}'))
+    .replace(/\r\n/g, '\n')
+  return parse(str, opts)
 }

package/tests/parse.spec.js

@@ -366,6 +366,30 @@ describe('Comment string parsing', function () {
       })
   })
 
+  /* eslint-disable no-tabs */
+  it('should parse tag with type, name and description `@tag {my.type} name description separated by tab`', function () {
+    expect(parse(function () {
+      /**
+       * @my-tag	{my.type}	name	description
+       */
+    })[0])
+      .to.eql({
+        line: 1,
+        source: '@my-tag\t{my.type}\tname\tdescription',
+        description: '',
+        tags: [{
+          tag: 'my-tag',
+          line: 2,
+          type: 'my.type',
+          name: 'name',
+          source: '@my-tag\t{my.type}\tname\tdescription',
+          description: 'description',
+          optional: false
+        }]
+      })
+  })
+  /* eslint-enable no-tabs */
+
   it('should parse tag with multiline description', function () {
     expect(parse(function () {
       /**
@@ -588,7 +612,7 @@ describe('Comment string parsing', function () {
        * @my-tag name.sub-name
        * @my-tag name.sub-name.sub-sub-name
        */
-    }, {dotted_names: true})[0])
+    }, { dotted_names: true })[0])
       .to.eql({
         line: 1,
         description: 'Description',
@@ -864,4 +888,154 @@ describe('Comment string parsing', function () {
         }]
       })
   })
+
+  it('should parse same line closing section (issue #22)', function () {
+    expect(parse(function () {
+      /**
+       * Start here
+       * Here is more stuff */
+      var a
+    })[0])
+      .to.eql({
+        description: 'Start here\nHere is more stuff',
+        line: 1,
+        source: 'Start here\nHere is more stuff',
+        tags: []
+      })
+  })
+
+  it('should tolerate inconsistent formatting (issue #29)', function () {
+    expect(parse(function () {
+      /**
+         * @param {Object} options 配置
+         * @return {Any} obj 组件返回的对象
+         * @example
+         * var widget = XX.showWidget('searchlist', {
+         *    onComplete: function() {
+         *          todoSomething();
+         *     }
+         * });
+     */
+    }, {
+      join: 1,
+      trim: false
+    })[0]).to.eql({
+      description: '',
+      line: 1,
+      source: "\n@param {Object} options 配置\n@return {Any} obj 组件返回的对象\n@example\nvar widget = XX.showWidget('searchlist', {\n   onComplete: function() {\n         todoSomething();\n    }\n});\n",
+      tags: [{
+        description: '配置',
+        line: 2,
+        name: 'options',
+        optional: false,
+        source: '@param {Object} options 配置',
+        tag: 'param',
+        type: 'Object'
+      }, {
+        description: '组件返回的对象',
+        line: 3,
+        name: 'obj',
+        optional: false,
+        source: '@return {Any} obj 组件返回的对象',
+        tag: 'return',
+        type: 'Any'
+      }, {
+        description: "widget = XX.showWidget('searchlist', {\n   onComplete: function() {\n         todoSomething();\n    }\n});\n",
+        line: 4,
+        name: '\nvar',
+        optional: false,
+        source: "@example\nvar widget = XX.showWidget('searchlist', {\n   onComplete: function() {\n         todoSomething();\n    }\n});\n",
+        tag: 'example',
+        type: ''
+      }]
+    })
+  })
+
+  it('should keep optional names spaces (issue #41)`', function () {
+    expect(parse(function () {
+      /**
+       * @section [Brand Colors] Here you can find all the brand colors
+       */
+    })[0])
+      .to.eql({
+        line: 1,
+        source: '@section [Brand Colors] Here you can find all the brand colors',
+        description: '',
+        tags: [{
+          tag: 'section',
+          line: 2,
+          type: '',
+          name: 'Brand Colors',
+          source: '@section [Brand Colors] Here you can find all the brand colors',
+          optional: true,
+          description: 'Here you can find all the brand colors'
+        }]
+      })
+  })
+
+  it('should keep quotes in description (issue #41)`', function () {
+    expect(parse(function () {
+      /**
+       * @section "Brand Colors" Here you can find all the brand colors
+       */
+    })[0])
+      .to.eql({
+        line: 1,
+        source: '@section "Brand Colors" Here you can find all the brand colors',
+        description: '',
+        tags: [{
+          tag: 'section',
+          line: 2,
+          type: '',
+          name: 'Brand Colors',
+          source: '@section "Brand Colors" Here you can find all the brand colors',
+          optional: false,
+          description: 'Here you can find all the brand colors'
+        }]
+      })
+  })
+
+  it('should use only quoted name (issue #41)`', function () {
+    expect(parse(function () {
+      /**
+       * @section "Brand Colors" Here you can find "all" the brand colors
+       */
+    })[0])
+      .to.eql({
+        line: 1,
+        source: '@section "Brand Colors" Here you can find "all" the brand colors',
+        description: '',
+        tags: [{
+          tag: 'section',
+          line: 2,
+          type: '',
+          name: 'Brand Colors',
+          source: '@section "Brand Colors" Here you can find "all" the brand colors',
+          optional: false,
+          description: 'Here you can find "all" the brand colors'
+        }]
+      })
+  })
+
+  it('should ignore inconsitent quoted groups (issue #41)`', function () {
+    expect(parse(function () {
+      /**
+       * @section "Brand Colors Here you can find all the brand colors
+       */
+    })[0])
+      .to.eql({
+        line: 1,
+        source: '@section "Brand Colors Here you can find all the brand colors',
+        description: '',
+        tags: [{
+          tag: 'section',
+          line: 2,
+          type: '',
+          name: '"Brand',
+          source: '@section "Brand Colors Here you can find all the brand colors',
+          optional: false,
+          description: 'Colors Here you can find all the brand colors'
+        }]
+      })
+  })
 })