comment-parser 0.5.4 → 0.6.2

package/.travis.yml

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

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# v0.6.2
+- document TypeScript definitions
+
+# v0.6.1
+- adjust strigifier indentation
+
+# v0.6.0
+- soft-drop node@6 support
+- migrate to ES6 syntax
+- allow to generate comments out of parsed data
+
+# v0.5.5
+- allow loose tag names, e.g. @.tag, @-tag
+
 # v0.5.4
 - allow quoted literal names, e.g. `@tag "My Var" description`
 

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,
@@ -160,6 +160,21 @@ This would produce following:
 }]
 ```
 
+## Stringifying
+
+One may also convert `comment-parser` JSON structures back into strings using
+the `stringify` method (`stringify(o:(Object|Array) [, opts:Object]):String`).
+
+This method accepts the JSON as its first argument and an optional options
+object with an `indent` property set to either a string or a number that
+will be used to determine the number of spaces of indent. The indent of the
+start of the doc block will be one space less than the indent of each line of
+asterisks for the sake of alignment as per usual practice.
+
+The `stringify` export delegates to the specialized methods `stringifyBlocks`,
+`stringifyBlock`, and `stringifyTag`, which are available on the `stringify`
+function object.
+
 ## Packaging
 
 `comment-parser` is CommonJS module and was primarely designed to be used with Node. Module `index.js` includes stream and file functionality. Use prser-only module in browser `comment-parser/parse.js`
@@ -168,4 +183,4 @@ This would produce following:
 
 ```
 > npm info --registry https://registry.npmjs.org comment-parser contributors
-```
+```

package/index.d.ts

@@ -2,28 +2,176 @@
 // Project: comment-parser
 // Definitions by: Javier "Ciberman" Mora <https://github.com/jhm-ciberman/>
 
-declare namespace CommentParser {
+declare namespace parse {
+
+  /**
+   * In case you need to parse tags in a different way you can specify custom parsers here.
+   * Each parser function takes string left after previous parsers were applied and the data produced by them.
+   * It should return either `undefined` or the new object, where `source` is the consumed substring.
+   */
+  export type Parser = (str: string, data: any) => { source: string, data: any };
+
+  /**
+   * Represents a parsed doc comment.
+   */
   export interface Comment {
+    /**
+     * A list of tags that are present in this doc comment.
+     */
     tags: Tag[];
+    /**
+     * The starting line in the source code of this doc comment.
+     */
     line: number;
+    /**
+     * The description of this doc comment. Empty string if no description was specified.
+     */
     description: string;
+    /**
+     * The source of this doc comment, exactly as it appeared in the doc comment before parsing.
+     */
     source: string;
   }
+
+  /**
+   * Represents a parsed tag. A tag has the following format:
+   * >  &#64;tag {type} [name=default] description
+   */
   export interface Tag {
+    /**
+     * The tag's kind, eg `param` or `return`.
+     */
     tag: string;
+    /**
+     * The name of this tag, ie the first word after the tag. Empty string if no name was specified.
+     */
     name: string;
+    /**
+     * `true` if the tag is optional (tag name enclosed in brackets), `false` otherwise.
+     */
     optional: boolean;
+    /**
+     * The type declaration of this tag that is enclosed in curly braces. Empty string if no type was specified.
+     */
     type: string;
+    /**
+     * The description of this tag that comes after the name. Empty string if no description was specified.
+     */
     description: string;
+    /**
+     * The line number where this tag starts
+     */
     line: number;
+    /**
+     * The source of this tag, exactly as it appeared in the doc comment before parsing.
+     */
     source: string;
+    /**
+     * The default value for this tag. `undefined` in case no default value was specified.
+     */
+    default?: string;
+    /**
+     * A list of errors that occurred during the parsing of this tag. `undefined` if not error occurred.
+     */
+    errors? : string[];
+    /**
+     * If `dotted_names` was set to `true`, a list of sub tags. `undefined` if `dotted_names` was set to `false` or if
+     * no sub tags exist.
+     */
+    tags?: Tag[];
   }
+  
+  /**
+   * Options for parsing doc comments.
+   */
   export interface Options {
-    parsers?: [(str: string, data: any) => { source: string, data: any }];
-    dotted_names?: boolean;
+    /**
+     * In case you need to parse tags in a different way you can specify custom parsers here.
+     * Each parser function takes string left after previous parsers were applied and the data produced by them.
+     * It should return either `undefined` or the new object, where `source` is the consumed substring.
+     * 
+     * If you specify custom parsers, the default parsers are overwritten, but you can access them via the constant
+     * `PARSERS`. 
+     */
+    parsers: Parser[];
+    /**
+     * By default dotted names like `name.subname.subsubname` will be expanded into nested sections, this can be
+     * prevented by passing `opts.dotted_names = false`.
+     */
+    dotted_names: boolean;
+    join: string | number | boolean;
+    /**
+     * `true` to trim whitespace at the start of each line, `false` otherwise.
+     */
+    trim: boolean;
+  }
+
+    /**
+   * Options for turning a parsed doc comment back into a string.
+   */
+  export interface StringifyOptions {
+    /**
+     * Indentation for each line. If a string is passed, that string is used verbatim to indent each line. If a number
+     * is passed, indents each line with that many whitespaces.
+     */
+    indent: string | number;
   }
+
+  export interface Stringify {
+    /**
+     * One may also convert comment-parser JSON structures back into strings using this stringify method.
+     * 
+     * This method accepts the JSON as its first argument and an optional options object with an indent property set to
+     * either a string or a number that will be used to determine the number of spaces of indent. The indent of the start
+     * of the doc block will be one space less than the indent of each line of asterisks for the sake of alignment as per
+     * usual practice.
+     * 
+     * The stringify export delegates to the specialized methods `stringifyBlocks`, `stringifyBlock`, and
+     * `stringifyTag`, which are available on the stringify function object.
+     * @param comment A tag, comment or a list of comments to stringify.
+     * @param options Options to control how the comment or comments are stringified.
+     * @return The stringified doc comment(s).
+     */
+    (comment: Tag | Comment | Comment[], options?: Partial<StringifyOptions>): string;
+    /**
+     * Similar to `stringify`, but only accepts a list of doc comments.
+     * @param comments A list of comments to stringify.
+     * @param options Options to control how the comments are stringified.
+     * @return The stringified doc comment(s).
+     */
+    stringifyBlocks(comments: Comment[], options?: Partial<StringifyOptions>): string;
+    /**
+     * Similar to `stringify`, but only accepts a single doc comment.
+     * @param comment A comment to stringify.
+     * @param options Options to control how the comment is stringified.
+     * @return The stringified doc comment(s).
+     */
+    stringifyBlock(comment: Comment, options?: Partial<StringifyOptions>): string;
+    /**
+     * Similar to `stringify`, but only accepts a single tag.
+     * @param tag A tag to stringify.
+     * @param options Options to control how the tag is stringified.
+     * @return The stringified doc comment(s).
+     */
+    stringifyTag(tag: Tag, options?: Partial<StringifyOptions>): string;
+  }
+
+  export const stringify: parse.Stringify;
+
+  /**
+   * The default list of parsers that is used to parse comments.
+   */
+  export const PARSERS: Record<"parse_tag" | "parse_type" | "parse_description" | "parse_name", Parser>
 }
 
-declare function parse(str: string, opts?: CommentParser.Options): [CommentParser.Comment];
+/**
+ * The main method of this module which takes comment string and returns an 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.
+ * @param str A string with doc comments and source code to parse.
+ * @param opts Options to control how the source string is parsed.
+ * @return The parsed list of doc comments.
+ */
+declare function parse(str: string, opts?: Partial<parse.Options>): [parse.Comment];
 
 export = parse;

package/index.js

@@ -1,36 +1,39 @@
 
 'use strict'
 
-var fs = require('fs')
-var stream = require('stream')
-var util = require('util')
+const fs = require('fs')
+const stream = require('stream')
 
-var parse = require('./parser')
+const parse = require('./parser')
+
+const stringify = require('./stringifier')
 
 module.exports = parse
 
-/* ------- Transform stream ------- */
+module.exports.stringify = stringify
 
-function Parser (opts) {
-  opts = opts || {}
-  stream.Transform.call(this, {objectMode: true})
-  this._extract = parse.mkextract(opts)
-}
+/* ------- Transform stream ------- */
 
-util.inherits(Parser, stream.Transform)
+class Parser extends stream.Transform {
+  constructor (opts) {
+    opts = opts || {}
+    super({ objectMode: true })
+    this._extract = parse.mkextract(opts)
+  }
 
-Parser.prototype._transform = function transform (data, encoding, done) {
-  var block
-  var lines = data.toString().split(/\n/)
+  _transform (data, encoding, done) {
+    let block
+    const lines = data.toString().split(/\n/)
 
-  while (lines.length) {
-    block = this._extract(lines.shift())
-    if (block) {
-      this.push(block)
+    while (lines.length) {
+      block = this._extract(lines.shift())
+      if (block) {
+        this.push(block)
+      }
     }
-  }
 
-  done()
+    done()
+  }
 }
 
 module.exports.stream = function stream (opts) {
@@ -40,15 +43,15 @@ module.exports.stream = function stream (opts) {
 /* ------- File parser ------- */
 
 module.exports.file = function file (file_path, done) {
-  var opts = {}
-  var collected = []
+  let opts = {}
+  const collected = []
 
   if (arguments.length === 3) {
     opts = done
     done = arguments[2]
   }
 
-  return fs.createReadStream(file_path, {encoding: 'utf8'})
+  return fs.createReadStream(file_path, { encoding: 'utf8' })
     .on('error', done)
     .pipe(new Parser(opts))
     .on('error', done)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-parser",
-  "version": "0.5.4",
+  "version": "0.6.2",
   "description": "Generic JSDoc-like comment parser. ",
   "main": "index.js",
   "types": "index.d.ts",
@@ -10,18 +10,23 @@
   "dependencies": {},
   "devDependencies": {
     "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": "^5.2.0",
-    "nodemon": "^1.18.9"
+    "eslint": "^6.0.1",
+    "eslint-config-standard": "^13.0.1",
+    "eslint-plugin-import": "^2.18.0",
+    "eslint-plugin-node": "^9.1.0",
+    "eslint-plugin-promise": "^4.2.1",
+    "eslint-plugin-standard": "^4.0.0",
+    "mocha": "^6.1.4",
+    "nodemon": "^1.19.1"
+  },
+  "engines": {
+    "node": ">= 6.0.0"
   },
   "scripts": {
-    "pretest": "eslint .",
-    "test": "mocha tests",
+    "lint:fix": "eslint --fix .",
+    "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": {
@@ -36,6 +41,8 @@
   "author": "Sergii Iavorskyi <yavorskiy.s@gmail.com> (https://github.com/yavorskiy)",
   "contributors": [
     "Alexej Yaroshevich (https://github.com/zxqfox)",
+    "Andre Wachsmuth (https://github.com/blutorange)",
+    "Brett Zamir (https://github.com/brettz9)",
     "Dieter Oberkofler (https://github.com/doberkofler)",
     "Evgeny Reznichenko (https://github.com/zxcabs)",
     "Javier \"Ciberma\" Mora (https://github.com/jhm-ciberman)",

package/parser.js

@@ -1,36 +1,21 @@
 
-var PARSERS = require('./parsers')
+'use strict'
 
-var MARKER_START = '/**'
-var MARKER_START_SKIP = '/***'
-var MARKER_END = '*/'
+const PARSERS = require('./parsers')
 
-/* ------- util functions ------- */
-
-function merge (/* ...objects */) {
-  var k, obj
-  var res = {}
-  var objs = Array.prototype.slice.call(arguments)
+const MARKER_START = '/**'
+const MARKER_START_SKIP = '/***'
+const MARKER_END = '*/'
 
-  for (var i = 0, l = objs.length; i < l; i++) {
-    obj = objs[i]
-    for (k in obj) {
-      if (obj.hasOwnProperty(k)) {
-        res[k] = obj[k]
-      }
-    }
-  }
-  return res
-}
+/* ------- util functions ------- */
 
 function find (list, filter) {
-  var k
-  var i = list.length
-  var matchs = true
+  let i = list.length
+  let matchs = true
 
   while (i--) {
-    for (k in filter) {
-      if (filter.hasOwnProperty(k)) {
+    for (const k in filter) {
+      if ({}.hasOwnProperty.call(filter, k)) {
         matchs = (filter[k] === list[i][k]) && matchs
       }
     }
@@ -44,17 +29,17 @@ function find (list, filter) {
 /**
  * Parses "@tag {type} name description"
  * @param {string} str Raw doc string
- * @param {Array[function]} parsers Array of parsers to be applied to the source
+ * @param {Array<function>} parsers Array of parsers to be applied to the source
  * @returns {object} parsed tag node
  */
 function parse_tag (str, parsers) {
   if (typeof str !== 'string' || str[0] !== '@') { return null }
 
-  var data = parsers.reduce(function (state, parser) {
-    var result
+  const data = parsers.reduce(function (state, parser) {
+    let result
 
     try {
-      result = parser(state.source, merge({}, state.data))
+      result = parser(state.source, Object.assign({}, state.data))
     } catch (err) {
       state.data.errors = (state.data.errors || [])
         .concat(parser.name + ': ' + err.message)
@@ -62,7 +47,7 @@ function parse_tag (str, parsers) {
 
     if (result) {
       state.source = state.source.slice(result.source.length)
-      state.data = merge(state.data, result.data)
+      state.data = Object.assign(state.data, result.data)
     }
 
     return state
@@ -83,17 +68,17 @@ function parse_tag (str, parsers) {
  * Parses comment block (array of String lines)
  */
 function parse_block (source, opts) {
-  var trim = opts.trim
+  const trim = opts.trim
     ? function trim (s) { return s.trim() }
     : function trim (s) { return s }
 
-  var source_str = source
-    .map(function (line) { return trim(line.source) })
+  let source_str = source
+    .map((line) => { return trim(line.source) })
     .join('\n')
 
   source_str = trim(source_str)
 
-  var start = source[0].number
+  const start = source[0].number
 
   // merge source lines into tags
   // we assume tag starts with "@"
@@ -101,13 +86,16 @@ function parse_block (source, opts) {
     .reduce(function (tags, line) {
       line.source = trim(line.source)
 
-      if (line.source.match(/^\s*@(\w+)/)) {
-        tags.push({source: [line.source], line: line.number})
+      if (line.source.match(/^\s*@(\S+)/)) {
+        tags.push({
+          source: [line.source],
+          line: line.number
+        })
       } else {
-        var tag = tags[tags.length - 1]
+        const tag = tags[tags.length - 1]
         if (opts.join !== undefined && opts.join !== false && opts.join !== 0 &&
             !line.startWithStar && tag.source.length > 0) {
-          var source
+          let source
           if (typeof opts.join === 'string') {
             source = opts.join + line.source.replace(/^\s+/, '')
           } else if (typeof opts.join === 'number') {
@@ -122,33 +110,33 @@ function parse_block (source, opts) {
       }
 
       return tags
-    }, [{source: []}])
-    .map(function (tag) {
+    }, [{ source: [] }])
+    .map((tag) => {
       tag.source = trim(tag.source.join('\n'))
       return tag
     })
 
   // Block description
-  var description = source.shift()
+  const description = source.shift()
 
   // skip if no descriptions and no tags
   if (description.source === '' && source.length === 0) {
     return null
   }
 
-  var tags = source.reduce(function (tags, tag) {
-    var tag_node = parse_tag(tag.source, opts.parsers)
+  const tags = source.reduce(function (tags, tag) {
+    const tag_node = parse_tag(tag.source, opts.parsers)
 
     if (!tag_node) { return tags }
 
     tag_node.line = tag.line
     tag_node.source = tag.source
 
-    if (opts.dotted_names && tag_node.name.indexOf('.') !== -1) {
-      var parent_name
-      var parent_tag
-      var parent_tags = tags
-      var parts = tag_node.name.split('.')
+    if (opts.dotted_names && tag_node.name.includes('.')) {
+      let parent_name
+      let parent_tag
+      let parent_tags = tags
+      const parts = tag_node.name.split('.')
 
       while (parts.length > 1) {
         parent_name = parts.shift()
@@ -181,7 +169,7 @@ function parse_block (source, opts) {
   }, [])
 
   return {
-    tags: tags,
+    tags,
     line: start,
     description: description.source,
     source: source_str
@@ -192,11 +180,11 @@ function parse_block (source, opts) {
  * Produces `extract` function with internal state initialized
  */
 function mkextract (opts) {
-  var chunk = null
-  var indent = 0
-  var number = 0
+  let chunk = null
+  let indent = 0
+  let number = 0
 
-  opts = merge({}, {
+  opts = Object.assign({}, {
     trim: true,
     dotted_names: false,
     parsers: [
@@ -212,11 +200,11 @@ function mkextract (opts) {
    * Return parsed block once fullfilled or null otherwise
    */
   return function extract (line) {
-    var result = null
-    var startPos = line.indexOf(MARKER_START)
-    var endPos = line.indexOf(MARKER_END)
+    let result = null
+    const startPos = line.indexOf(MARKER_START)
+    const endPos = line.indexOf(MARKER_END)
 
-    // if open marker detected and it's not skip one
+    // if open marker detected and it's not, skip one
     if (startPos !== -1 && line.indexOf(MARKER_START_SKIP) !== startPos) {
       chunk = []
       indent = startPos + MARKER_START.length
@@ -224,12 +212,12 @@ function mkextract (opts) {
 
     // if we are on middle of comment block
     if (chunk) {
-      var lineStart = indent
-      var startWithStar = false
+      let lineStart = indent
+      let startWithStar = false
 
       // figure out if we slice from opening marker pos
       // or line start is shifted to the left
-      var nonSpaceChar = line.match(/\S/)
+      const nonSpaceChar = line.match(/\S/)
 
       // skip for the first line starting with /** (fresh chunk)
       // it always has the right indentation
@@ -244,8 +232,8 @@ function mkextract (opts) {
 
       // slice the line until end or until closing marker start
       chunk.push({
-        number: number,
-        startWithStar: startWithStar,
+        number,
+        startWithStar,
         source: line.slice(lineStart, endPos === -1 ? line.length : endPos)
       })
 
@@ -265,17 +253,16 @@ function mkextract (opts) {
 /* ------- Public API ------- */
 
 module.exports = function parse (source, opts) {
-  var block
-  var blocks = []
-  var extract = mkextract(opts)
-  var lines = source.split(/\n/)
+  const blocks = []
+  const extract = mkextract(opts)
+  const lines = source.split(/\n/)
 
-  for (var i = 0, l = lines.length; i < l; i++) {
-    block = extract(lines.shift())
+  lines.forEach((line) => {
+    const block = extract(line)
     if (block) {
       blocks.push(block)
     }
-  }
+  })
 
   return blocks
 }

package/parsers.js

@@ -1,5 +1,7 @@
+'use strict'
+
 function skipws (str) {
-  var i = 0
+  let i = 0
   do {
     if (str[i] !== ' ' && str[i] !== '\t') { return i }
   } while (++i < str.length)
@@ -8,25 +10,25 @@ function skipws (str) {
 
 /* ------- default parsers ------- */
 
-var PARSERS = {}
+const PARSERS = {}
 
 PARSERS.parse_tag = function parse_tag (str) {
-  var result = str.match(/^\s*@(\S+)/)
+  const result = str.match(/^\s*@(\S+)/)
 
   if (!result) { throw new Error('Invalid `@tag`, missing @ symbol') }
 
   return {
     source: result[0],
-    data: {tag: result[1]}
+    data: { tag: result[1] }
   }
 }
 
 PARSERS.parse_type = function parse_type (str, data) {
   if (data.errors && data.errors.length) { return null }
 
-  var pos = skipws(str)
-  var res = ''
-  var curlies = 0
+  let pos = skipws(str)
+  let res = ''
+  let curlies = 0
 
   if (str[pos] !== '{') { return null }
 
@@ -41,20 +43,20 @@ PARSERS.parse_type = function parse_type (str, data) {
 
   return {
     source: str.slice(0, pos),
-    data: {type: res.slice(1, -1)}
+    data: { type: res.slice(1, -1) }
   }
 }
 
 PARSERS.parse_name = function parse_name (str, data) {
   if (data.errors && data.errors.length) { return null }
 
-  var pos = skipws(str)
-  var name = ''
-  var brackets = 0
-  var res = {optional: false}
+  let pos = skipws(str)
+  let name = ''
+  let brackets = 0
+  let res = { optional: false }
 
   // if it starts with quoted group assume it is a literal
-  var quotedGroups = str.slice(pos).split('"')
+  const quotedGroups = str.slice(pos).split('"')
   if (quotedGroups.length > 1 && quotedGroups[0] === '' && quotedGroups.length % 2 === 1) {
     name = quotedGroups[1]
     pos += name.length + 2
@@ -69,14 +71,14 @@ PARSERS.parse_name = function parse_name (str, data) {
 
     if (brackets !== 0) { throw new Error('Invalid `name`, unpaired brackets') }
 
-    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.indexOf('=') !== -1) {
-        var parts = name.split('=')
+        const parts = name.split('=')
         name = parts[0]
         res.default = parts[1].replace(/^(["'])(.+)(\1)$/, '$2')
       }
@@ -94,12 +96,12 @@ 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)+)?/)
+  const result = str.match(/^\s+((.|\s)+)?/)
 
   if (result) {
     return {
       source: result[0],
-      data: {description: result[1] === undefined ? '' : result[1]}
+      data: { description: result[1] === undefined ? '' : result[1] }
     }
   }
 

package/stringifier.js

@@ -0,0 +1,57 @@
+'use strict'
+
+const getIndent = (indent) => {
+  return typeof indent === 'number' ? ' '.repeat(indent) : indent
+}
+
+module.exports = exports = function stringify (arg, opts) {
+  if (Array.isArray(arg)) {
+    return stringifyBlocks(arg, opts)
+  }
+  if (arg && typeof arg === 'object') {
+    if ('tag' in arg) {
+      return stringifyTag(arg, opts)
+    }
+    if ('tags' in arg) {
+      return stringifyBlock(arg, opts)
+    }
+  }
+  throw new TypeError('Unexpected argument passed to `stringify`.')
+}
+
+const stringifyBlocks = exports.stringifyBlocks = function stringifyBlocks (
+  blocks, { indent = '' } = {}
+) {
+  const indnt = getIndent(indent)
+  return blocks.reduce((s, block) => {
+    return s + stringifyBlock(block, { indent })
+  }, (indnt ? indnt.slice(0, -1) : '') + '/**\n') + indnt + '*/'
+}
+
+const stringifyBlock = exports.stringifyBlock = function stringifyBlock (
+  block, { indent = '' } = {}
+) {
+  // block.line
+  const indnt = getIndent(indent)
+  return (block.description ? `${indnt}* ${block.description}\n${indnt}*\n` : '') +
+    block.tags.reduce((s, tag) => {
+      return s + stringifyTag(tag, { indent })
+    }, '')
+}
+
+const stringifyTag = exports.stringifyTag = function stringifyTag (
+  tag, { indent = '' } = {}
+) {
+  const indnt = getIndent(indent)
+  const {
+    type, name, optional, description, tag: tagName, default: deflt //, line , source
+  } = tag
+  return indnt + `* @${tagName}` +
+    (type ? ` {${type}}` : '') +
+    (name ? ` ${
+      optional ? '[' : ''
+    }${name}${deflt ? `=${deflt}` : ''}${
+      optional ? ']' : ''
+    }` : '') +
+    (description ? ` ${description.replace(/\n/g, '\n' + indnt + '* ')}` : '') + '\n'
+}

package/tests/custom-parsers.spec.js

@@ -1,6 +1,8 @@
 /* eslint no-unused-vars:off */
-var expect = require('chai').expect
-var parse = require('./parse')
+'use strict'
+
+const { expect } = require('chai')
+const parse = require('./parse')
 
 describe('parse() with custom tag parsers', function () {
   function sample () {
@@ -11,7 +13,7 @@ describe('parse() with custom tag parsers', function () {
   }
 
   it('should use `opts.parsers`', function () {
-    var parsers = [
+    const parsers = [
       function everything (str) {
         return {
           source: str,
@@ -26,7 +28,7 @@ describe('parse() with custom tag parsers', function () {
       }
     ]
 
-    expect(parse(sample, {parsers: parsers})[0])
+    expect(parse(sample, { parsers: parsers })[0])
       .to.eql({
         line: 1,
         description: '',
@@ -44,17 +46,17 @@ describe('parse() with custom tag parsers', function () {
   })
 
   it('should merge parsers result', function () {
-    var parsers = [
+    const parsers = [
       function parser1 (str) {
         return {
           source: '',
-          data: {tag: 'tag'}
+          data: { tag: 'tag' }
         }
       },
       function parser2 (str) {
         return {
           source: '',
-          data: {type: 'type'}
+          data: { type: 'type' }
         }
       },
       function parser3 (str) {
@@ -68,7 +70,7 @@ describe('parse() with custom tag parsers', function () {
       }
     ]
 
-    expect(parse(sample, {parsers: parsers})[0])
+    expect(parse(sample, { parsers: parsers })[0])
       .to.eql({
         line: 1,
         description: '',
@@ -86,11 +88,11 @@ describe('parse() with custom tag parsers', function () {
   })
 
   it('should catch parser exceptions and populate `errors` field', function () {
-    var parsers = [
+    const parsers = [
       function parser1 (str) {
         return {
           source: '',
-          data: {tag: 'tag'}
+          data: { tag: 'tag' }
         }
       },
       function parser2 (str) {
@@ -102,12 +104,12 @@ describe('parse() with custom tag parsers', function () {
       function parser4 (str) {
         return {
           source: '',
-          data: {name: 'name'}
+          data: { name: 'name' }
         }
       }
     ]
 
-    expect(parse(sample, {parsers: parsers})[0])
+    expect(parse(sample, { parsers: parsers })[0])
       .to.eql({
         line: 1,
         description: '',

package/tests/files.spec.js

@@ -1,9 +1,11 @@
 /* eslint no-unused-vars:off */
-var fs = require('fs')
-var path = require('path')
-var stream = require('readable-stream')
-var expect = require('chai').expect
-var parse = require('../index')
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const stream = require('readable-stream')
+const { expect } = require('chai')
+const parse = require('../index')
 
 describe('File parsing', function () {
   it('should parse the file by path', function (done) {
@@ -41,11 +43,11 @@ describe('File parsing', function () {
   })
 
   it('should return `Transform` stream', function (done) {
-    var count = 0
+    let count = 0
 
-    var readable = fs.createReadStream(path.resolve(__dirname, 'fixtures/sample.js'), {encoding: 'utf8'})
+    const readable = fs.createReadStream(path.resolve(__dirname, 'fixtures/sample.js'), { encoding: 'utf8' })
 
-    var writable = new stream.Writable({objectMode: true})
+    const writable = new stream.Writable({ objectMode: true })
     writable._write = function (data, encoding, done) {
       count++
       done()

package/tests/parse.js

@@ -7,10 +7,12 @@
  *
  */
 
-var parse = require('../index')
+'use strict'
+
+const parse = require('../index')
 
 module.exports = function (func, opts) {
-  var str = func.toString()
+  let str = func.toString()
   str = str
     .slice(str.indexOf('{') + 1, str.lastIndexOf('}'))
     .replace(/\r\n/g, '\n')

package/tests/parse.spec.js

@@ -1,7 +1,8 @@
 /* eslint no-unused-vars:off */
 
-var expect = require('chai').expect
-var parse = require('./parse')
+'use strict'
+const { expect } = require('chai')
+const parse = require('./parse')
 
 describe('Comment string parsing', function () {
   it('should parse doc block with description', function () {
@@ -145,7 +146,7 @@ describe('Comment string parsing', function () {
   })
 
   it('should parse multiple doc blocks', function () {
-    var p = parse(function () {
+    const p = parse(function () {
       /**
        * Description first line
        */
@@ -459,6 +460,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 () {
       /**

package/tests/stringify.spec.js

@@ -0,0 +1,80 @@
+'use strict'
+
+const { expect } = require('chai')
+
+const parser = require('../')
+
+describe('Comment stringifying', function () {
+  it('should stringify doc block with description', function () {
+    const expected = `/**
+* Singleline or multiline description text. Line breaks are preserved.
+*
+* @some-tag {Type} name Singleline or multiline description text
+* @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
+*/`
+    const parsed = parser(expected)
+
+    expect(parsed).to.be.an('array')
+
+    const stringified = parser.stringify(parsed)
+
+    expect(stringified).to.eq(expected)
+  })
+
+  it('should stringify indented doc block with description', function () {
+    const expected = `   /**
+    * Singleline or multiline description text. Line breaks are preserved.
+    *
+    * @some-tag {Type} name Singleline or multiline description text
+    * @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
+    */`
+    const parsed = parser(expected)
+
+    expect(parsed).to.be.an('array')
+
+    const stringified = parser.stringify(parsed, { indent: '    ' })
+
+    expect(stringified).to.eq(expected)
+  })
+
+  it('should stringify numeric indented doc block with description', function () {
+    const expected = `   /**
+    * Singleline or multiline description text. Line breaks are preserved.
+    *
+    * @some-tag {Type} name Singleline or multiline description text
+    * @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
+    */`
+    const parsed = parser(expected)
+
+    expect(parsed).to.be.an('array')
+
+    const stringified = parser.stringify(parsed, { indent: 4 })
+
+    expect(stringified).to.eq(expected)
+  })
+
+  it('should stringify numeric indented doc block without description', function () {
+    const expected = `   /**
+    * @param Foo
+    */`
+    const parsed = parser(expected)
+
+    expect(parsed).to.be.an('array')
+
+    const stringified = parser.stringify(parsed, { indent: 4 })
+
+    expect(stringified).to.eq(expected)
+  })
+})