comment-parser 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# v0.3.2
-- fix RegExp for `description` extraction to allow $ char
+# v0.4.0
+- allow to preserve exact source and line numbers with `opts.trim = false`
 
 # v0.3.1
 - use `readable-stream` fro Node 0.8 comatibility
-- allow to pass optional parameters to `parse.file(path [,opts], done)`  
+- allow to pass optional parameters to `parse.file(path [,opts], done)`
 - allow `parse.stream` to work with Buffers in addition to strings
 
 # v0.3.0

package/README.md

@@ -5,7 +5,7 @@ Generic JSDoc-like comment parser. This library is not intended to be documentat
 
 `npm install comment-parser`
 
-Module provides `parse(s:String[, opts:Object]):Object` function which takes `/** ... */` comment string and returns array  of objects with parsed data.
+Module provides `parse(s:String[, options:Object]):Object` function which takes `/** ... */` comment string and returns array  of objects with parsed data.
 
 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.
 
@@ -64,17 +64,31 @@ this would be parsed into following
 }]
 ```
 
-By default dotted names like `name.subname.subsubname` will be expanded into nested sections, this can be prevented by passing `opts.dotted_names = false`.
-
 Invalid comment blocks are skipped. Comments starting with `/*` and `/***` are considered not valid.
 
 Also you can parse entire file with `parse.file('path/to/file', callback)` or acquire an instance of [Transform](http://nodejs.org/api/stream.html#stream_class_stream_transform) stream with `parse.stream()`.
 
+
+### Options
+
+#### dotted_names `true`
+
+Tells parser to expand dotted names like `name.subname.subsubname` into nested sections
+
+#### trim `true`
+
+Makes parser to trim white spaces, set it to `false` to preserve exact source and line numbers
+
+#### parsers, `[PARSERS.{parse_tag, parse_type, parse_name, parse_description}]`
+
+Array of alternative parsers (read below).
+
+
 ## Custom parsers
 
 
 In case you need to parse tags in different way you can pass `opts.parsers = [parser1, ..., parserN]`, where each parser is `function name(str:String, data:Object):{source:String, data:Object}`.
-
+	
 Each parser function takes string left after previous parsers applied and data produced by them. And returns `null` or `{source: '', data:{}}` where `source` is consumed substring and `data` is a payload with tag node fields.
 
 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:
@@ -86,23 +100,23 @@ Tag node data is build by merging result bits from all parsers. Here is some exa
  */
 parse(source, {parsers: [
 	// takes entire string
-	function parse_tag(str, data) {
-		return {source: ' @tag', data: {tag: 'tag'}};
-	},
+	function parse_tag(str, data) { 
+		return {source: ' @tag', data: {tag: 'tag'}}; 
+	}, 
 	// parser throwing exception
 	function check_tag(str, data) {
-		if (allowed_tags.indexOf(data.tag) === -1) {
+		if (allowed_tags.indexOf(data.tag) === -1) { 
 			throw new Error('Unrecognized tag "' + data.tag + '"');
 		}			
 	},
 	// takes the rest of the string after ' @tag''
-	function parse_name1(str, data) {
-		return {source: ' name', data: {name: 'name1'}};
+	function parse_name1(str, data) { 
+		return {source: ' name', data: {name: 'name1'}}; 
 	},
 	// alternative name parser
-	function parse_name2(str, data) {
-		return {source: ' name', data: {name: 'name2'}};
-	}
+	function parse_name2(str, data) { 
+		return {source: ' name', data: {name: 'name2'}}; 
+	}	
 ]});
 ```
 
@@ -135,10 +149,9 @@ This would produce following:
 ## Contributors
 
 
+- [Sergii Iavorskyi](https://github.com/yavorskiy)
 - [Alexej Yaroshevich](https://github.com/zxqfox)
-- [Evgeny Reznichenko](https://github.com/zxcabs)
 - [Jordan Harband](https://github.com/ljharb)
-- [Sergii Iavorskyi](https://github.com/yavorskiy)
 
 
 Happy coding :)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-parser",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Generic JSDoc-like comment parser. ",
   "main": "index.js",
   "directories": {

package/parser.js

@@ -115,7 +115,7 @@ PARSERS.parse_name = function parse_name(str, data) {
 PARSERS.parse_description = function parse_description(str, data) {
   if (data.errors && data.errors.length) { return null; }
 
-  var result = str.match(/^\s+((.|\s)+)?/);
+  var result = str.match(/^\s+([^$]+)?/);
 
   if (result) {
     return {
@@ -347,4 +347,4 @@ module.exports = function parse(source, opts) {
 };
 
 module.exports.PARSERS = PARSERS;
-module.exports.mkextract = mkextract;
+module.exports.mkextract = mkextract;

package/tests/parse.spec.js

@@ -10,7 +10,7 @@ describe('Comment string parsing', function() {
    * 0 function() {
    * 1  // source with comments
    * 2 }
-   *
+   * 
    */
 
   function parsed(func, opts) {
@@ -39,11 +39,11 @@ describe('Comment string parsing', function() {
     expect(parsed(function(){
       /**
        *
-       *
+       * 
        * Description first line
        *
        * Description second line
-       *
+       * 
        */
       var a;
     })[0])
@@ -59,7 +59,7 @@ describe('Comment string parsing', function() {
 
     expect(parsed(function(){
       /**
-       *
+       * 
        */
       var a;
     }).length)
@@ -136,10 +136,10 @@ describe('Comment string parsing', function() {
     expect(parsed(function(){
       /**
        *
-       *
+       * 
        *   Description first line
        *     second line
-       *
+       * 
        *       third line
        */
       var a;
@@ -178,7 +178,7 @@ describe('Comment string parsing', function() {
   it('should parse `@tag`', function() {
       expect(parsed(function(){
         /**
-         *
+         * 
          * @my-tag
          */
         var a;
@@ -252,14 +252,14 @@ describe('Comment string parsing', function() {
       })[0])
         .to.eql({
           line        : 1,
-          source      : '@my-tag {my.type} name',
+          source      : '@my-tag {my.type} name',    
           description : '',
           tags: [{
             tag         : 'my-tag',
             line        : 2,
             type        : 'my.type',
             name        : 'name',
-            source      : '@my-tag {my.type} name',
+            source      : '@my-tag {my.type} name',    
             description : '',
             optional    : false
           }]
@@ -281,7 +281,7 @@ describe('Comment string parsing', function() {
             line        : 2,
             type        : 'my.type',
             name        : 'name',
-            source      : '@my-tag {my.type} name description',
+            source      : '@my-tag {my.type} name description',    
             description : 'description',
             optional    : false
           }]
@@ -589,26 +589,4 @@ describe('Comment string parsing', function() {
           }]
         });
   });
-
-  it('parses $ in description`', function() {
-    expect(parsed(function(){
-      /**
-       * @my-tag {String} name description with $ char
-       */
-    })[0])
-      .to.eql({
-        line        : 1,
-        source      : '@my-tag {String} name description with $ char',
-        description : '',
-        tags: [{
-          tag         : 'my-tag',
-          line        : 2,
-          type        : 'String',
-          name        : 'name',
-          source      : '@my-tag {String} name description with $ char',
-          optional    : false,
-          description : 'description with $ char'
-        }]
-      });
-  });
 });