comment-parser 0.5.1 → 0.5.5

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,16 @@
+# v0.5.5
+- allow loose tag names, e.g. @.tag, @-tag
+
+# 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

package/README.md

@@ -9,7 +9,7 @@ Module provides `parse(s:String[, opts:Object]):Object` function which takes `/*
 
 It is not trying to detect relations between tags or somehow recognize their meaning. Any tag can be used, as long as it satisfies the format.
 
-```
+```javascript
 /**
  * Singleline or multiline description text. Line breaks are preserved.
  *
@@ -24,7 +24,7 @@ It is not trying to detect relations between tags or somehow recognize their mea
 
 this would be parsed into following
 
-```javascript
+```json
 [{
   "tags": [{
     "tag": "some-tag",
@@ -78,7 +78,7 @@ By default dotted names like `name.subname.subsubname` will be expanded into nes
 
 Below are examples of acceptable comment formats
 
-```
+```javascript
 /** online comment */
 
 /** first line
@@ -111,7 +111,7 @@ Each parser function takes string left after previous parsers applied and data p
 
 Tag node data is build by merging result bits from all parsers. Here is some example that is not doing actual parsing but is demonstrating the flow:
 
-```
+```javascript
 /**
  * Source to be parsed below
  * @tag {type} name Description
@@ -140,12 +140,12 @@ parse(source, {parsers: [
 
 This would produce following:
 
-```
+```json
 [{
   "tags": [{
     "tag": "tag",
     "errors": [
-      "check_tag: Unrecognized tag \\"tag\\""
+      "check_tag: Unrecognized tag \"tag\""
     ],
     "name": "name2",
     "optional": false,
@@ -168,4 +168,4 @@ This would produce following:
 
 ```
 > 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,28 +1,28 @@
 {
   "name": "comment-parser",
-  "version": "0.5.1",
+  "version": "0.5.5",
   "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",
-    "eslint": "^4.7.1",
+    "chai": "^4.2.0",
+    "eslint": "^5.16.0",
     "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 .",
-    "test": "mocha tests",
+    "test:lint": "eslint .",
+    "test:unit": "mocha tests",
+    "test": "npm run test:lint && npm run test:unit",
     "watch": "nodemon -q -i node_modules -x npm test"
   },
   "repository": {
@@ -39,6 +39,7 @@
     "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)"
   ],

package/parser.js

@@ -101,7 +101,7 @@ function parse_block (source, opts) {
     .reduce(function (tags, line) {
       line.source = trim(line.source)
 
-      if (line.source.match(/^\s*@(\w+)/)) {
+      if (line.source.match(/^\s*@(\S+)/)) {
         tags.push({source: [line.source], line: line.number})
       } else {
         var tag = tags[tags.length - 1]

package/parsers.js

@@ -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

@@ -459,6 +459,47 @@ describe('Comment string parsing', function () {
       })
   })
 
+  it('should tolerate loose tag names', function () {
+    expect(parse(function () {
+      /**
+         Description text
+         @.tag0 tagname Tag 0 description
+         @-tag1 tagname Tag 1 description
+         @+tag2 tagname Tag 2 description
+      */
+    })[0])
+      .eql({
+        description: 'Description text',
+        source: 'Description text\n@.tag0 tagname Tag 0 description\n@-tag1 tagname Tag 1 description\n@+tag2 tagname Tag 2 description',
+        line: 1,
+        tags: [{
+          tag: '.tag0',
+          name: 'tagname',
+          optional: false,
+          description: 'Tag 0 description',
+          type: '',
+          line: 3,
+          source: '@.tag0 tagname Tag 0 description'
+        }, {
+          tag: '-tag1',
+          name: 'tagname',
+          optional: false,
+          description: 'Tag 1 description',
+          type: '',
+          line: 4,
+          source: '@-tag1 tagname Tag 1 description'
+        }, {
+          tag: '+tag2',
+          name: 'tagname',
+          optional: false,
+          description: 'Tag 2 description',
+          type: '',
+          line: 5,
+          source: '@+tag2 tagname Tag 2 description'
+        }]
+      })
+  })
+
   it('should tolerate default value with whitespces `@tag {my.type} [name=John Doe]`', function () {
     expect(parse(function () {
       /**
@@ -612,7 +653,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',
@@ -888,4 +929,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'
+        }]
+      })
+  })
 })