documentation - npm Package Compare versions

Comparing version 1.0.3 to 1.0.4

bin/documentation.js

@@ -20,6 +20,3 @@ #!/usr/bin/env node
   lint = require('../streams/lint.js'),
-  github = require('../streams/github.js'),
-  normalize = require('../streams/normalize.js'),
-  flatten = require('../streams/flatten.js'),
-  filterAccess = require('../streams/filter_access.js');
+  github = require('../streams/github.js');
 
@@ -112,8 +109,7 @@ var yargs = require('yargs')
 
-var docStream = documentation(inputs)
-  .pipe(normalize())
+var docStream = documentation(inputs, {
+    private: argv.private
+  })
   .pipe(argv.lint ? lint() : new PassThrough({ objectMode: true }))
   .pipe(argv.g ? github() : new PassThrough({ objectMode: true }))
-  .pipe(flatten())
-  .pipe(filterAccess(argv.private ? [] : undefined))
   .pipe(formatter);
@@ -120,0 +116,0 @@

gl-example/index.json

@@ -1,1 +0,1 @@
-[{"description":"Generate JavaScript documentation as a list of parsed JSDoc\ncomments, given a root file as a path.","tags":[{"title":"name","description":null,"name":"documentation"},{"title":"param","description":"files to process","type":{"type":"UnionType","elements":[{"type":"TypeApplication","expression":{"type":"NameExpression","name":"Array"},"applications":[{"type":"NameExpression","name":"String"}]},{"type":"NameExpression","name":"String"}]},"name":"indexes"},{"title":"returns","description":"stream of output","type":{"type":"NameExpression","name":"Object"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":25,"column":0},"end":{"line":57,"column":2}},"file":"/Users/tmcw/src/documentation/index.js","code":"'use strict';\n\nvar mdeps = require('module-deps'),\n  path = require('path'),\n  PassThrough = require('stream').PassThrough,\n  sort = require('./streams/sort'),\n  parse = require('./streams/parse'),\n  inferName = require('./streams/infer_name'),\n  inferKind = require('./streams/infer_kind'),\n  inferMembership = require('./streams/infer_membership');\n\n// Skip external modules. Based on http://git.io/pzPO.\nvar externalModuleRegexp = process.platform === 'win32' ?\n  /^(\\.|\\w:)/ :\n  /^[\\/.]/;\n\n/**\n * Generate JavaScript documentation as a list of parsed JSDoc\n * comments, given a root file as a path.\n *\n * @name documentation\n * @param {Array<String>|String} indexes files to process\n * @return {Object} stream of output\n */\nmodule.exports = function (indexes) {\n  var md = mdeps({\n    filter: function (id) {\n      return externalModuleRegexp.test(id);\n    }\n  });\n\n  if (typeof indexes === 'string') {\n    indexes = [indexes];\n  }\n\n  indexes.forEach(function (index) {\n    md.write(path.resolve(index));\n  });\n  md.end();\n\n  var end = new PassThrough({ objectMode: true });\n\n  function deferErrors(stream) {\n    return stream.on('error', function (a, b, c) {\n      end.emit('error', a, b, c);\n      end.emit('end');\n    });\n  }\n\n  return md\n    .pipe(deferErrors(parse()))\n    .pipe(deferErrors(inferName()))\n    .pipe(sort())\n    .pipe(deferErrors(inferKind()))\n    .pipe(deferErrors(inferMembership()))\n    .pipe(end);\n};","path":"index.js","github":"https://github.com/documentationjs/documentation/blob/7fe9e1bbfe0fc08a5fea4866d0a46ab84435f441/index.js#L25-L57"},"name":"documentation","params":[{"title":"param","description":"files to process","type":{"type":"UnionType","elements":[{"type":"TypeApplication","expression":{"type":"NameExpression","name":"Array"},"applications":[{"type":"NameExpression","name":"String"}]},{"type":"NameExpression","name":"String"}]},"name":"indexes"}],"returns":[{"title":"returns","description":"stream of output","type":{"type":"NameExpression","name":"Object"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["documentation"]},{"description":"Comment-out a shebang line that may sit at the top of a file,\nmaking it executable on linux-like systems.","tags":[{"title":"param","description":"the source code in full","type":{"type":"NameExpression","name":"String"},"name":"code"},{"title":"returns","description":"code","type":{"type":"NameExpression","name":"String"}},{"title":"example","description":"var foo = commentShebang('#!/usr/bin/env/node');\nfoo === '//#!/usr/bin/env/node';"},{"title":"name","name":"commentShebang"}],"context":{"loc":{"start":{"line":19,"column":0},"end":{"line":21,"column":1}},"file":"/Users/tmcw/src/documentation/streams/parse.js","code":"'use strict';\n\nvar doctrine = require('doctrine'),\n  espree = require('espree'),\n  through = require('through'),\n  types = require('ast-types'),\n  extend = require('extend'),\n  isJSDocComment = require('../lib/is_jsdoc_comment');\n\n/**\n * Comment-out a shebang line that may sit at the top of a file,\n * making it executable on linux-like systems.\n * @param {String} code the source code in full\n * @return {String} code\n * @example\n * var foo = commentShebang('#!/usr/bin/env/node');\n * foo === '//#!/usr/bin/env/node';\n */\nfunction commentShebang(code) {\n  return (code[0] === '#' && code[1] === '!') ? '//' + code : code;\n}\n\nvar espreeConfig = {\n  loc: true,\n  attachComment: true,\n  // specify parsing features (default only has blockBindings: true)\n    ecmaFeatures: {\n        // enable parsing of arrow functions\n        arrowFunctions: true,\n        // enable parsing of let/const\n        blockBindings: true,\n        // enable parsing of destructured arrays and objects\n        destructuring: true,\n        // enable parsing of regular expression y flag\n        regexYFlag: true,\n        // enable parsing of regular expression u flag\n        regexUFlag: true,\n        // enable parsing of template strings\n        templateStrings: true,\n        // enable parsing of binary literals\n        binaryLiterals: true,\n        // enable parsing of ES6 octal literals\n        octalLiterals: true,\n        // enable parsing unicode code point escape sequences\n        unicodeCodePointEscapes: true,\n        // enable parsing of default parameters\n        defaultParams: true,\n        // enable parsing of rest parameters\n        restParams: true,\n        // enable parsing of for-of statement\n        forOf: true,\n        // enable parsing computed object literal properties\n        objectLiteralComputedProperties: true,\n        // enable parsing of shorthand object literal methods\n        objectLiteralShorthandMethods: true,\n        // enable parsing of shorthand object literal properties\n        objectLiteralShorthandProperties: true,\n        // Allow duplicate object literal properties (except '__proto__')\n        objectLiteralDuplicateProperties: true,\n        // enable parsing of generators/yield\n        generators: true,\n        // enable parsing spread operator\n        spread: true,\n        // enable parsing classes\n        classes: true,\n        // enable parsing of modules\n        modules: true,\n        // enable React JSX parsing\n        jsx: true,\n        // enable return in global scope\n        globalReturn: true\n    }\n};\n\n/**\n * Documentation stream parser: this receives a module-dep item,\n * reads the file, parses the JavaScript, parses the JSDoc, and\n * emits parsed comments.\n * @name parse\n * @param {Object} data a chunk of data provided by module-deps\n * @return {undefined} this emits data\n */\nmodule.exports = function () {\n  return through(function (data) {\n    try {\n      var code = commentShebang(data.source),\n        ast = espree.parse(code, espreeConfig),\n        stream = this;\n    } catch(e) {\n      e.message += ' (' + data.file + ')';\n      this.emit('error', e);\n      this.emit('end');\n    }\n\n    types.visit(ast, {\n      visitNode: function (path) {\n        /**\n         * Parse a comment with doctrine and decorate the result with file position and code context.\n         *\n         * @param {Object} comment the current state of the parsed JSDoc comment\n         * @return {undefined} this emits data\n         */\n        function parseComment(comment) {\n          var parsedComment = doctrine.parse(comment.value, { unwrap: true });\n\n          parsedComment.context = {\n            loc: extend({}, path.value.loc),\n            file: data.file\n          };\n\n          // This is non-enumerable so that it doesn't get stringified in output; e.g. by the\n          // documentation binary.\n          Object.defineProperty(parsedComment.context, 'ast', {\n            enumerable: false,\n            value: path\n          });\n\n          if (path.parent && path.parent.node) {\n            parsedComment.context.code = code.substring\n              .apply(code, path.parent.node.range);\n          }\n\n          stream.push(parsedComment);\n        }\n\n        (path.value.leadingComments || [])\n          .filter(isJSDocComment)\n          .forEach(parseComment);\n\n        this.traverse(path);\n      }\n    });\n  });\n};","path":"streams/parse.js","github":"https://github.com/documentationjs/documentation/blob/7fe9e1bbfe0fc08a5fea4866d0a46ab84435f441/streams/parse.js#L19-L21"},"params":[{"title":"param","description":"the source code in full","type":{"type":"NameExpression","name":"String"},"name":"code"}],"returns":[{"title":"returns","description":"code","type":{"type":"NameExpression","name":"String"}}],"examples":["<span class=\"hljs-keyword\">var</span> foo = commentShebang(<span class=\"hljs-string\">'#!/usr/bin/env/node'</span>);\nfoo === <span class=\"hljs-string\">'//#!/usr/bin/env/node'</span>;"],"name":"commentShebang","members":{"instance":[],"static":[]},"path":["commentShebang"]},{"description":"Create a transform stream that attempts to infer a `kind` tag from other\ntags or from the context.","tags":[{"title":"name","description":null,"name":"inferKind"},{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":12,"column":0},"end":{"line":34,"column":2}},"file":"/Users/tmcw/src/documentation/streams/infer_kind.js","code":"'use strict';\n\nvar through = require('through');\n\n/**\n * Create a transform stream that attempts to infer a `kind` tag from other\n * tags or from the context.\n *\n * @name inferKind\n * @return {stream.Transform}\n */\nmodule.exports = function () {\n  return through(function (comment) {\n    function hasTag(title) {\n      return comment.tags.some(function (tag) {\n        return tag.title === title;\n      });\n    }\n\n    if (!hasTag('kind')) {\n      ['class', 'constant', 'event', 'external', 'file',\n        'function', 'member', 'mixin', 'module', 'namespace', 'typedef'].forEach(function (kind) {\n          if (hasTag(kind)) {\n            comment.tags.push({\n              title: 'kind',\n              kind: kind\n            });\n          }\n        });\n    }\n\n    this.push(comment);\n  });\n};","path":"streams/infer_kind.js","github":"https://github.com/documentationjs/documentation/blob/7fe9e1bbfe0fc08a5fea4866d0a46ab84435f441/streams/infer_kind.js#L12-L34"},"name":"inferKind","returns":[{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["inferKind"]},{"description":"Create a transform stream that uses code structure to infer\n`memberof`, `instance`, and `static` tags from the placement of JSDoc\nannotations within a file","tags":[{"title":"name","description":null,"name":"inferMembership"},{"title":"returns","description":"stream","type":{"type":"NameExpression","name":"Stream.Transform"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":17,"column":0},"end":{"line":186,"column":2}},"file":"/Users/tmcw/src/documentation/streams/infer_membership.js","code":"'use strict';\n\nvar through = require('through'),\n  types = require('ast-types'),\n  n = types.namedTypes,\n  isJSDocComment = require('../lib/is_jsdoc_comment'),\n  doctrine = require('doctrine');\n\n/**\n * Create a transform stream that uses code structure to infer\n * `memberof`, `instance`, and `static` tags from the placement of JSDoc\n * annotations within a file\n *\n * @name inferMembership\n * @returns {Stream.Transform} stream\n */\nmodule.exports = function () {\n  return through(function (comment) {\n    if (comment.tags.some(function (tag) {\n      return tag.title === 'memberof';\n    })) {\n      this.push(comment);\n      return;\n    }\n\n    if (findLendsTag(comment)) {\n      return;\n    }\n\n    /**\n     * Extract and return the chain of identifiers from the left hand side of expressions\n     * of the forms `Foo = ...`, `Foo.bar = ...`, `Foo.bar.baz = ...`, etc.\n     *\n     * @param {NodePath} path AssignmentExpression, MemberExpression, or Identifier\n     * @returns {Array<string>} identifiers\n     * @private\n     */\n    function extractIdentifiers(path) {\n      var identifiers = [];\n\n      types.visit(path, {\n        visitNode: function () {\n          return false;\n        },\n\n        visitAssignmentExpression: function (path) {\n          this.traverse(path);\n        },\n\n        visitMemberExpression: function (path) {\n          this.traverse(path);\n        },\n\n        visitIdentifier: function (path) {\n          identifiers.push(path.node.name);\n          return false;\n        }\n      });\n\n      return identifiers;\n    }\n\n    /**\n     * Set `memberof` and `instance`/`static` tags on `comment` based on the\n     * array of `identifiers`. If the last element of the `identifiers` is\n     * `\"prototype\"`, it is assumed to be an instance member; otherwise static.\n     *\n     * @param {Array<string>} identifiers array of identifier names\n     * @returns {undefined} mutates `comment`\n     * @private\n     */\n    function inferMembership(identifiers) {\n      if (identifiers[identifiers.length - 1] === 'prototype') {\n        comment.tags.push({\n          title: 'memberof',\n          description: identifiers.slice(0, -1).join('.')\n        });\n\n        comment.tags.push({\n          title: 'instance'\n        });\n      } else {\n        comment.tags.push({\n          title: 'memberof',\n          description: identifiers.join('.')\n        });\n\n        comment.tags.push({\n          title: 'static'\n        });\n      }\n    }\n\n    function findLendsTag(comment) {\n      for (var i = 0; i < comment.tags.length; i++) {\n        if (comment.tags[i].title === 'lends') {\n          return comment.tags[i];\n        }\n      }\n    }\n\n    function findLendsIdentifiers(node) {\n      if (!node || !node.leadingComments) {\n        return;\n      }\n\n      for (var i = 0; i < node.leadingComments.length; i++) {\n        var comment = node.leadingComments[i];\n        if (isJSDocComment(comment)) {\n          var lendsTag = findLendsTag(doctrine.parse(comment.value, { unwrap: true }));\n          if (lendsTag) {\n            return lendsTag.description.split('.');\n          }\n        }\n      }\n    }\n\n    var path = comment.context.ast;\n    var identifiers;\n\n    /*\n     * Deal with an oddity of espree: the jsdoc comment is attached to a different\n     * node in the two expressions `a.b = c` vs `a.b = function () {}`.\n     */\n    if (n.ExpressionStatement.check(path.node) &&\n        n.AssignmentExpression.check(path.node.expression) &&\n        n.MemberExpression.check(path.node.expression.left)) {\n      path = path.get('expression').get('left');\n    }\n\n    /*\n     * Same as above but for `b: c` vs `b: function () {}`.\n     */\n    if (n.Property.check(path.node) &&\n        n.Identifier.check(path.node.key)) {\n      path = path.get('key');\n    }\n\n    // Foo.bar = ...;\n    // Foo.prototype.bar = ...;\n    // Foo.bar.baz = ...;\n    if (n.MemberExpression.check(path.node)) {\n      identifiers = extractIdentifiers(path);\n      if (identifiers.length >= 2) {\n        inferMembership(identifiers.slice(0, -1));\n      }\n    }\n\n    // /** @lends Foo */{ bar: ... }\n    if (n.Identifier.check(path.node) &&\n      n.Property.check(path.parent.node) &&\n      n.ObjectExpression.check(path.parent.parent.node)) {\n      // The @lends comment is sometimes attached to the first property rather than\n      // the object expression itself.\n      identifiers = findLendsIdentifiers(path.parent.parent.node) ||\n          findLendsIdentifiers(path.parent.parent.node.properties[0]);\n      if (identifiers) {\n        inferMembership(identifiers);\n      }\n    }\n\n    // Foo = { bar: ... };\n    // Foo.prototype = { bar: ... };\n    // Foo.bar = { baz: ... };\n    if (n.Identifier.check(path.node) &&\n        n.Property.check(path.parent.node) &&\n        n.ObjectExpression.check(path.parent.parent.node) &&\n        n.AssignmentExpression.check(path.parent.parent.parent.node)) {\n      identifiers = extractIdentifiers(path.parent.parent.parent);\n      if (identifiers.length >= 1) {\n        inferMembership(identifiers);\n      }\n    }\n\n    // var Foo = { bar: ... }\n    if (n.Identifier.check(path.node) &&\n        n.Property.check(path.parent.node) &&\n        n.ObjectExpression.check(path.parent.parent.node) &&\n        n.VariableDeclarator.check(path.parent.parent.parent.node)) {\n      identifiers = [path.parent.parent.parent.node.id.name];\n      inferMembership(identifiers);\n    }\n\n    this.push(comment);\n  });\n};","path":"streams/infer_membership.js","github":"https://github.com/documentationjs/documentation/blob/7fe9e1bbfe0fc08a5fea4866d0a46ab84435f441/streams/infer_membership.js#L17-L186"},"name":"inferMembership","returns":[{"title":"returns","description":"stream","type":{"type":"NameExpression","name":"Stream.Transform"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["inferMembership"]},{"description":"Create a transform stream that attempts to infer a `name` tag from the context.","tags":[{"title":"name","description":null,"name":"inferName"},{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":12,"column":0},"end":{"line":52,"column":2}},"file":"/Users/tmcw/src/documentation/streams/infer_name.js","code":"'use strict';\n\nvar through = require('through'),\n  types = require('ast-types');\n\n/**\n * Create a transform stream that attempts to infer a `name` tag from the context.\n *\n * @name inferName\n * @return {stream.Transform}\n */\nmodule.exports = function () {\n  return through(function (comment) {\n    // If this comment is already explicitly named, simply pass it\n    // through the stream without doing any inference.\n    if (comment.tags.some(function (tag) {\n      return tag.title === 'name';\n    })) {\n      this.push(comment);\n      return;\n    }\n\n    // The strategy here is to do a depth-first traversal of the AST,\n    // looking for nodes with a \"name\" property, with exceptions as needed.\n    // For example, name inference for a MemberExpression `foo.bar = baz` will\n    // infer the named based on the `property` of the MemberExpression (`bar`)\n    // rather than the `object` (`foo`).\n    types.visit(comment.context.ast, {\n      inferName: function (path, value) {\n        if (value && value.name) {\n          comment.tags.push({\n            title: 'name',\n            name: value.name\n          });\n          this.abort();\n        } else {\n          this.traverse(path);\n        }\n      },\n\n      visitNode: function (path) {\n        this.inferName(path, path.value);\n      },\n\n      visitMemberExpression: function (path) {\n        this.inferName(path, path.value.property);\n      }\n    });\n\n    this.push(comment);\n  });\n};","path":"streams/infer_name.js","github":"https://github.com/documentationjs/documentation/blob/7fe9e1bbfe0fc08a5fea4866d0a46ab84435f441/streams/infer_name.js#L12-L52"},"name":"inferName","returns":[{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["inferName"]},{"description":"Detect whether a comment is a JSDoc comment: it must be a block\ncomment which starts with two asterisks, not any other number of asterisks.\n\nThe code parser automatically strips out the first asterisk that's\nrequired for the comment to be a comment at all, so we count the remaining\ncomments.","tags":[{"title":"name","description":null,"name":"isJSDocComment"},{"title":"param","description":"an ast-types node of the comment","type":{"type":"NameExpression","name":"Object"},"name":"comment"},{"title":"returns","description":"whether it is valid","type":{"type":"NameExpression","name":"boolean"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":15,"column":0},"end":{"line":18,"column":2}},"file":"/Users/tmcw/src/documentation/lib/is_jsdoc_comment.js","code":"'use strict';\n\n/**\n * Detect whether a comment is a JSDoc comment: it must be a block\n * comment which starts with two asterisks, not any other number of asterisks.\n *\n * The code parser automatically strips out the first asterisk that's\n * required for the comment to be a comment at all, so we count the remaining\n * comments.\n *\n * @name isJSDocComment\n * @param {Object} comment an ast-types node of the comment\n * @return {boolean} whether it is valid\n */\nmodule.exports = function isJSDocComment(comment) {\n  var asterisks = comment.value.match(/^(\\*+)/);\n  return comment.type === 'Block' && asterisks && asterisks[ 1 ].length === 1;\n};","path":"lib/is_jsdoc_comment.js","github":"https://github.com/documentationjs/documentation/blob/7fe9e1bbfe0fc08a5fea4866d0a46ab84435f441/lib/is_jsdoc_comment.js#L15-L18"},"name":"isJSDocComment","params":[{"title":"param","description":"an ast-types node of the comment","type":{"type":"NameExpression","name":"Object"},"name":"comment"}],"returns":[{"title":"returns","description":"whether it is valid","type":{"type":"NameExpression","name":"boolean"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["isJSDocComment"]},{"description":"Documentation stream parser: this receives a module-dep item,\nreads the file, parses the JavaScript, parses the JSDoc, and\nemits parsed comments.","tags":[{"title":"name","description":null,"name":"parse"},{"title":"param","description":"a chunk of data provided by module-deps","type":{"type":"NameExpression","name":"Object"},"name":"data"},{"title":"returns","description":"this emits data","type":{"type":"UndefinedLiteral"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":83,"column":0},"end":{"line":134,"column":2}},"file":"/Users/tmcw/src/documentation/streams/parse.js","code":"'use strict';\n\nvar doctrine = require('doctrine'),\n  espree = require('espree'),\n  through = require('through'),\n  types = require('ast-types'),\n  extend = require('extend'),\n  isJSDocComment = require('../lib/is_jsdoc_comment');\n\n/**\n * Comment-out a shebang line that may sit at the top of a file,\n * making it executable on linux-like systems.\n * @param {String} code the source code in full\n * @return {String} code\n * @example\n * var foo = commentShebang('#!/usr/bin/env/node');\n * foo === '//#!/usr/bin/env/node';\n */\nfunction commentShebang(code) {\n  return (code[0] === '#' && code[1] === '!') ? '//' + code : code;\n}\n\nvar espreeConfig = {\n  loc: true,\n  attachComment: true,\n  // specify parsing features (default only has blockBindings: true)\n    ecmaFeatures: {\n        // enable parsing of arrow functions\n        arrowFunctions: true,\n        // enable parsing of let/const\n        blockBindings: true,\n        // enable parsing of destructured arrays and objects\n        destructuring: true,\n        // enable parsing of regular expression y flag\n        regexYFlag: true,\n        // enable parsing of regular expression u flag\n        regexUFlag: true,\n        // enable parsing of template strings\n        templateStrings: true,\n        // enable parsing of binary literals\n        binaryLiterals: true,\n        // enable parsing of ES6 octal literals\n        octalLiterals: true,\n        // enable parsing unicode code point escape sequences\n        unicodeCodePointEscapes: true,\n        // enable parsing of default parameters\n        defaultParams: true,\n        // enable parsing of rest parameters\n        restParams: true,\n        // enable parsing of for-of statement\n        forOf: true,\n        // enable parsing computed object literal properties\n        objectLiteralComputedProperties: true,\n        // enable parsing of shorthand object literal methods\n        objectLiteralShorthandMethods: true,\n        // enable parsing of shorthand object literal properties\n        objectLiteralShorthandProperties: true,\n        // Allow duplicate object literal properties (except '__proto__')\n        objectLiteralDuplicateProperties: true,\n        // enable parsing of generators/yield\n        generators: true,\n        // enable parsing spread operator\n        spread: true,\n        // enable parsing classes\n        classes: true,\n        // enable parsing of modules\n        modules: true,\n        // enable React JSX parsing\n        jsx: true,\n        // enable return in global scope\n        globalReturn: true\n    }\n};\n\n/**\n * Documentation stream parser: this receives a module-dep item,\n * reads the file, parses the JavaScript, parses the JSDoc, and\n * emits parsed comments.\n * @name parse\n * @param {Object} data a chunk of data provided by module-deps\n * @return {undefined} this emits data\n */\nmodule.exports = function () {\n  return through(function (data) {\n    try {\n      var code = commentShebang(data.source),\n        ast = espree.parse(code, espreeConfig),\n        stream = this;\n    } catch(e) {\n      e.message += ' (' + data.file + ')';\n      this.emit('error', e);\n      this.emit('end');\n    }\n\n    types.visit(ast, {\n      visitNode: function (path) {\n        /**\n         * Parse a comment with doctrine and decorate the result with file position and code context.\n         *\n         * @param {Object} comment the current state of the parsed JSDoc comment\n         * @return {undefined} this emits data\n         */\n        function parseComment(comment) {\n          var parsedComment = doctrine.parse(comment.value, { unwrap: true });\n\n          parsedComment.context = {\n            loc: extend({}, path.value.loc),\n            file: data.file\n          };\n\n          // This is non-enumerable so that it doesn't get stringified in output; e.g. by the\n          // documentation binary.\n          Object.defineProperty(parsedComment.context, 'ast', {\n            enumerable: false,\n            value: path\n          });\n\n          if (path.parent && path.parent.node) {\n            parsedComment.context.code = code.substring\n              .apply(code, path.parent.node.range);\n          }\n\n          stream.push(parsedComment);\n        }\n\n        (path.value.leadingComments || [])\n          .filter(isJSDocComment)\n          .forEach(parseComment);\n\n        this.traverse(path);\n      }\n    });\n  });\n};","path":"streams/parse.js","github":"https://github.com/documentationjs/documentation/blob/7fe9e1bbfe0fc08a5fea4866d0a46ab84435f441/streams/parse.js#L83-L134"},"name":"parse","params":[{"title":"param","description":"a chunk of data provided by module-deps","type":{"type":"NameExpression","name":"Object"},"name":"data"}],"returns":[{"title":"returns","description":"this emits data","type":{"type":"UndefinedLiteral"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["parse"]},{"description":"Parse a comment with doctrine and decorate the result with file position and code context.","tags":[{"title":"param","description":"the current state of the parsed JSDoc comment","type":{"type":"NameExpression","name":"Object"},"name":"comment"},{"title":"returns","description":"this emits data","type":{"type":"UndefinedLiteral"}},{"title":"name","name":"parseComment"}],"context":{"loc":{"start":{"line":103,"column":8},"end":{"line":124,"column":9}},"file":"/Users/tmcw/src/documentation/streams/parse.js","code":"{\n        /**\n         * Parse a comment with doctrine and decorate the result with file position and code context.\n         *\n         * @param {Object} comment the current state of the parsed JSDoc comment\n         * @return {undefined} this emits data\n         */\n        function parseComment(comment) {\n          var parsedComment = doctrine.parse(comment.value, { unwrap: true });\n\n          parsedComment.context = {\n            loc: extend({}, path.value.loc),\n            file: data.file\n          };\n\n          // This is non-enumerable so that it doesn't get stringified in output; e.g. by the\n          // documentation binary.\n          Object.defineProperty(parsedComment.context, 'ast', {\n            enumerable: false,\n            value: path\n          });\n\n          if (path.parent && path.parent.node) {\n            parsedComment.context.code = code.substring\n              .apply(code, path.parent.node.range);\n          }\n\n          stream.push(parsedComment);\n        }\n\n        (path.value.leadingComments || [])\n          .filter(isJSDocComment)\n          .forEach(parseComment);\n\n        this.traverse(path);\n      }","path":"streams/parse.js","github":"https://github.com/documentationjs/documentation/blob/7fe9e1bbfe0fc08a5fea4866d0a46ab84435f441/streams/parse.js#L103-L124"},"params":[{"title":"param","description":"the current state of the parsed JSDoc comment","type":{"type":"NameExpression","name":"Object"},"name":"comment"}],"returns":[{"title":"returns","description":"this emits data","type":{"type":"UndefinedLiteral"}}],"name":"parseComment","members":{"instance":[],"static":[]},"path":["parseComment"]},{"description":"Create a stream.Transform that sorts its input of comments\nby the name tag, if any, and otherwise by filename.","tags":[{"title":"name","description":null,"name":"sort"},{"title":"returns","description":"a transform stream","type":{"type":"NameExpression","name":"stream.Transform"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":9,"column":0},"end":{"line":23,"column":2}},"file":"/Users/tmcw/src/documentation/streams/sort.js","code":"var sort = require('sort-stream');\n\n/**\n * Create a stream.Transform that sorts its input of comments\n * by the name tag, if any, and otherwise by filename.\n * @name sort\n * @return {stream.Transform} a transform stream\n */\nmodule.exports = function () {\n\n  function getSortKey(comment) {\n    for (var i = 0; i < comment.tags.length; i++) {\n      if (comment.tags[i].title === 'name') {\n        return comment.tags[i].name;\n      }\n    }\n    return comment.context.file;\n  }\n\n  return sort(function (a, b) {\n    return getSortKey(a) > getSortKey(b);\n  });\n};","path":"streams/sort.js","github":"https://github.com/documentationjs/documentation/blob/7fe9e1bbfe0fc08a5fea4866d0a46ab84435f441/streams/sort.js#L9-L23"},"name":"sort","returns":[{"title":"returns","description":"a transform stream","type":{"type":"NameExpression","name":"stream.Transform"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["sort"]}]
+[{"description":"Exclude given access levels from the generated documentation: this allows\nusers to write documentation for non-public members by using the\n`@private` tag.","tags":[{"title":"name","description":null,"name":"access"},{"title":"public","description":null,"type":null},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":15,"column":0},"end":{"line":22,"column":2}},"file":"/Users/tmcw/src/documentation/streams/filter_access.js","code":"'use strict';\n\nvar through = require('through');\n\n/**\n * Exclude given access levels from the generated documentation: this allows\n * users to write documentation for non-public members by using the\n * `@private` tag.\n *\n * @name access\n * @public\n * @param {Array<String>} [levels=[private]] excluded access levels.\n * @return {stream.Transform}\n */\nmodule.exports = function (levels) {\n  levels = levels || ['private'];\n  return through(function (comment) {\n    if (levels.indexOf(comment.access) === -1) {\n      this.push(comment);\n    }\n  });\n};","path":"streams/filter_access.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/streams/filter_access.js#L15-L22"},"name":"access","access":"public","memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["access"]},{"description":"Comment-out a shebang line that may sit at the top of a file,\nmaking it executable on linux-like systems.","tags":[{"title":"param","description":"the source code in full","type":{"type":"NameExpression","name":"String"},"name":"code"},{"title":"returns","description":"code","type":{"type":"NameExpression","name":"String"}},{"title":"example","description":"var foo = commentShebang('#!/usr/bin/env/node');\nfoo === '//#!/usr/bin/env/node';"},{"title":"name","name":"commentShebang"}],"context":{"loc":{"start":{"line":19,"column":0},"end":{"line":21,"column":1}},"file":"/Users/tmcw/src/documentation/streams/parse.js","code":"'use strict';\n\nvar doctrine = require('doctrine'),\n  espree = require('espree'),\n  through = require('through'),\n  types = require('ast-types'),\n  extend = require('extend'),\n  isJSDocComment = require('../lib/is_jsdoc_comment');\n\n/**\n * Comment-out a shebang line that may sit at the top of a file,\n * making it executable on linux-like systems.\n * @param {String} code the source code in full\n * @return {String} code\n * @example\n * var foo = commentShebang('#!/usr/bin/env/node');\n * foo === '//#!/usr/bin/env/node';\n */\nfunction commentShebang(code) {\n  return (code[0] === '#' && code[1] === '!') ? '//' + code : code;\n}\n\nvar espreeConfig = {\n  loc: true,\n  attachComment: true,\n  // specify parsing features (default only has blockBindings: true)\n    ecmaFeatures: {\n        // enable parsing of arrow functions\n        arrowFunctions: true,\n        // enable parsing of let/const\n        blockBindings: true,\n        // enable parsing of destructured arrays and objects\n        destructuring: true,\n        // enable parsing of regular expression y flag\n        regexYFlag: true,\n        // enable parsing of regular expression u flag\n        regexUFlag: true,\n        // enable parsing of template strings\n        templateStrings: true,\n        // enable parsing of binary literals\n        binaryLiterals: true,\n        // enable parsing of ES6 octal literals\n        octalLiterals: true,\n        // enable parsing unicode code point escape sequences\n        unicodeCodePointEscapes: true,\n        // enable parsing of default parameters\n        defaultParams: true,\n        // enable parsing of rest parameters\n        restParams: true,\n        // enable parsing of for-of statement\n        forOf: true,\n        // enable parsing computed object literal properties\n        objectLiteralComputedProperties: true,\n        // enable parsing of shorthand object literal methods\n        objectLiteralShorthandMethods: true,\n        // enable parsing of shorthand object literal properties\n        objectLiteralShorthandProperties: true,\n        // Allow duplicate object literal properties (except '__proto__')\n        objectLiteralDuplicateProperties: true,\n        // enable parsing of generators/yield\n        generators: true,\n        // enable parsing spread operator\n        spread: true,\n        // enable parsing classes\n        classes: true,\n        // enable parsing of modules\n        modules: true,\n        // enable React JSX parsing\n        jsx: true,\n        // enable return in global scope\n        globalReturn: true\n    }\n};\n\n/**\n * Documentation stream parser: this receives a module-dep item,\n * reads the file, parses the JavaScript, parses the JSDoc, and\n * emits parsed comments.\n * @name parse\n * @param {Object} data a chunk of data provided by module-deps\n * @return {undefined} this emits data\n */\nmodule.exports = function () {\n  return through(function (data) {\n    try {\n      var code = commentShebang(data.source),\n        ast = espree.parse(code, espreeConfig),\n        stream = this;\n    } catch(e) {\n      e.message += ' (' + data.file + ')';\n      this.emit('error', e);\n      this.emit('end');\n    }\n\n    types.visit(ast, {\n      visitNode: function (path) {\n        /**\n         * Parse a comment with doctrine and decorate the result with file position and code context.\n         *\n         * @param {Object} comment the current state of the parsed JSDoc comment\n         * @return {undefined} this emits data\n         */\n        function parseComment(comment) {\n          var parsedComment = doctrine.parse(comment.value, { unwrap: true });\n\n          parsedComment.context = {\n            loc: extend({}, path.value.loc),\n            file: data.file\n          };\n\n          // This is non-enumerable so that it doesn't get stringified in output; e.g. by the\n          // documentation binary.\n          Object.defineProperty(parsedComment.context, 'ast', {\n            enumerable: false,\n            value: path\n          });\n\n          if (path.parent && path.parent.node) {\n            parsedComment.context.code = code.substring\n              .apply(code, path.parent.node.range);\n          }\n\n          stream.push(parsedComment);\n        }\n\n        (path.value.leadingComments || [])\n          .filter(isJSDocComment)\n          .forEach(parseComment);\n\n        this.traverse(path);\n      }\n    });\n  });\n};","path":"streams/parse.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/streams/parse.js#L19-L21"},"params":[{"title":"param","description":"the source code in full","type":{"type":"NameExpression","name":"String"},"name":"code"}],"returns":[{"title":"returns","description":"code","type":{"type":"NameExpression","name":"String"}}],"examples":["<span class=\"hljs-keyword\">var</span> foo = commentShebang(<span class=\"hljs-string\">'#!/usr/bin/env/node'</span>);\nfoo === <span class=\"hljs-string\">'//#!/usr/bin/env/node'</span>;"],"name":"commentShebang","members":{"instance":[],"static":[]},"path":["commentShebang"]},{"description":"Create a transform stream that flattens tags in an opinionated way.\n\nThe following tags are assumed to be singletons, and are flattened\nto a top-level property on the result whose value is extracted from\nthe tag:\n\n * `@name`\n * `@memberof`\n * `@classdesc`\n * `@kind`\n * `@access`\n\nThe following tags are flattened to a top-level array-valued property:\n\n * `@param` (to `params` property)\n * `@returns` (to `returns` property)\n * `@example` (to `examples` property)\n\nThe `@global`, `@static`, `@instance`, and `@inner` tags are flattened\nto a `scope` property whose value is `\"global\"`, `\"static\"`, `\"instance\"`,\nor `\"inner\"`.\n\nThe `@access`, `@public`, `@protected`, and `@private` tags are flattened\nto an `access` property whose value is `\"protected\"` or `\"private\"`.\nThe assumed default value is `\"public\"`, so `@access public` or `@public`\ntags result in no `access` property.","tags":[{"title":"name","description":null,"name":"flatten"},{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":37,"column":0},"end":{"line":47,"column":2}},"file":"/Users/tmcw/src/documentation/streams/flatten.js","code":"'use strict';\n\nvar through = require('through'),\n  extend = require('extend');\n\n/**\n * Create a transform stream that flattens tags in an opinionated way.\n *\n * The following tags are assumed to be singletons, and are flattened\n * to a top-level property on the result whose value is extracted from\n * the tag:\n *\n *  * `@name`\n *  * `@memberof`\n *  * `@classdesc`\n *  * `@kind`\n *  * `@access`\n *\n * The following tags are flattened to a top-level array-valued property:\n *\n *  * `@param` (to `params` property)\n *  * `@returns` (to `returns` property)\n *  * `@example` (to `examples` property)\n *\n * The `@global`, `@static`, `@instance`, and `@inner` tags are flattened\n * to a `scope` property whose value is `\"global\"`, `\"static\"`, `\"instance\"`,\n * or `\"inner\"`.\n *\n * The `@access`, `@public`, `@protected`, and `@private` tags are flattened\n * to an `access` property whose value is `\"protected\"` or `\"private\"`.\n * The assumed default value is `\"public\"`, so `@access public` or `@public`\n * tags result in no `access` property.\n *\n * @name flatten\n * @return {stream.Transform}\n */\nmodule.exports = function () {\n  return through(function (comment) {\n    var result = extend({}, comment);\n\n    comment.tags.forEach(function (tag) {\n      (flatteners[tag.title] || function () {})(result, tag);\n    });\n\n    this.push(result);\n  });\n};\n\nvar flatteners = {\n  'name': function (result, tag) {\n    result.name = tag.name;\n  },\n  'memberof': function (result, tag) {\n    result.memberof = tag.description;\n  },\n  'classdesc': function (result, tag) {\n    result.classdesc = tag.description;\n  },\n  'kind': function (result, tag) {\n    result.kind = tag.kind;\n  },\n  'param': function (result, tag) {\n    if (!result.params) {\n      result.params = [];\n    }\n    result.params.push(tag);\n  },\n  'returns': function (result, tag) {\n    if (!result.returns) {\n      result.returns = [];\n    }\n    result.returns.push(tag);\n  },\n  'augments': function (result, tag) {\n    if (!result.augments) {\n      result.augments = [];\n    }\n    result.augments.push(tag);\n  },\n  'example': function (result, tag) {\n    if (!result.examples) {\n      result.examples = [];\n    }\n    result.examples.push(tag.description);\n  },\n  'global': function (result) {\n    result.scope = 'global';\n  },\n  'static': function (result) {\n    result.scope = 'static';\n  },\n  'instance': function (result) {\n    result.scope = 'instance';\n  },\n  'inner': function (result) {\n    result.scope = 'inner';\n  },\n  'access': function (result, tag) {\n    result.access = tag.access;\n  },\n  'public': function (result) {\n    result.access = 'public';\n  },\n  'protected': function (result) {\n    result.access = 'protected';\n  },\n  'private': function (result) {\n    result.access = 'private';\n  }\n};","path":"streams/flatten.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/streams/flatten.js#L37-L47"},"name":"flatten","returns":[{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["flatten"]},{"description":"Create a transform stream that attempts to infer a `kind` tag from other\ntags or from the context.","tags":[{"title":"name","description":null,"name":"inferKind"},{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":12,"column":0},"end":{"line":34,"column":2}},"file":"/Users/tmcw/src/documentation/streams/infer_kind.js","code":"'use strict';\n\nvar through = require('through');\n\n/**\n * Create a transform stream that attempts to infer a `kind` tag from other\n * tags or from the context.\n *\n * @name inferKind\n * @return {stream.Transform}\n */\nmodule.exports = function () {\n  return through(function (comment) {\n    function hasTag(title) {\n      return comment.tags.some(function (tag) {\n        return tag.title === title;\n      });\n    }\n\n    if (!hasTag('kind')) {\n      ['class', 'constant', 'event', 'external', 'file',\n        'function', 'member', 'mixin', 'module', 'namespace', 'typedef'].forEach(function (kind) {\n          if (hasTag(kind)) {\n            comment.tags.push({\n              title: 'kind',\n              kind: kind\n            });\n          }\n        });\n    }\n\n    this.push(comment);\n  });\n};","path":"streams/infer_kind.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/streams/infer_kind.js#L12-L34"},"name":"inferKind","returns":[{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["inferKind"]},{"description":"Create a transform stream that uses code structure to infer\n`memberof`, `instance`, and `static` tags from the placement of JSDoc\nannotations within a file","tags":[{"title":"name","description":null,"name":"inferMembership"},{"title":"returns","description":"stream","type":{"type":"NameExpression","name":"Stream.Transform"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":17,"column":0},"end":{"line":186,"column":2}},"file":"/Users/tmcw/src/documentation/streams/infer_membership.js","code":"'use strict';\n\nvar through = require('through'),\n  types = require('ast-types'),\n  n = types.namedTypes,\n  isJSDocComment = require('../lib/is_jsdoc_comment'),\n  doctrine = require('doctrine');\n\n/**\n * Create a transform stream that uses code structure to infer\n * `memberof`, `instance`, and `static` tags from the placement of JSDoc\n * annotations within a file\n *\n * @name inferMembership\n * @returns {Stream.Transform} stream\n */\nmodule.exports = function () {\n  return through(function (comment) {\n    if (comment.tags.some(function (tag) {\n      return tag.title === 'memberof';\n    })) {\n      this.push(comment);\n      return;\n    }\n\n    if (findLendsTag(comment)) {\n      return;\n    }\n\n    /**\n     * Extract and return the chain of identifiers from the left hand side of expressions\n     * of the forms `Foo = ...`, `Foo.bar = ...`, `Foo.bar.baz = ...`, etc.\n     *\n     * @param {NodePath} path AssignmentExpression, MemberExpression, or Identifier\n     * @returns {Array<string>} identifiers\n     * @private\n     */\n    function extractIdentifiers(path) {\n      var identifiers = [];\n\n      types.visit(path, {\n        visitNode: function () {\n          return false;\n        },\n\n        visitAssignmentExpression: function (path) {\n          this.traverse(path);\n        },\n\n        visitMemberExpression: function (path) {\n          this.traverse(path);\n        },\n\n        visitIdentifier: function (path) {\n          identifiers.push(path.node.name);\n          return false;\n        }\n      });\n\n      return identifiers;\n    }\n\n    /**\n     * Set `memberof` and `instance`/`static` tags on `comment` based on the\n     * array of `identifiers`. If the last element of the `identifiers` is\n     * `\"prototype\"`, it is assumed to be an instance member; otherwise static.\n     *\n     * @param {Array<string>} identifiers array of identifier names\n     * @returns {undefined} mutates `comment`\n     * @private\n     */\n    function inferMembership(identifiers) {\n      if (identifiers[identifiers.length - 1] === 'prototype') {\n        comment.tags.push({\n          title: 'memberof',\n          description: identifiers.slice(0, -1).join('.')\n        });\n\n        comment.tags.push({\n          title: 'instance'\n        });\n      } else {\n        comment.tags.push({\n          title: 'memberof',\n          description: identifiers.join('.')\n        });\n\n        comment.tags.push({\n          title: 'static'\n        });\n      }\n    }\n\n    function findLendsTag(comment) {\n      for (var i = 0; i < comment.tags.length; i++) {\n        if (comment.tags[i].title === 'lends') {\n          return comment.tags[i];\n        }\n      }\n    }\n\n    function findLendsIdentifiers(node) {\n      if (!node || !node.leadingComments) {\n        return;\n      }\n\n      for (var i = 0; i < node.leadingComments.length; i++) {\n        var comment = node.leadingComments[i];\n        if (isJSDocComment(comment)) {\n          var lendsTag = findLendsTag(doctrine.parse(comment.value, { unwrap: true }));\n          if (lendsTag) {\n            return lendsTag.description.split('.');\n          }\n        }\n      }\n    }\n\n    var path = comment.context.ast;\n    var identifiers;\n\n    /*\n     * Deal with an oddity of espree: the jsdoc comment is attached to a different\n     * node in the two expressions `a.b = c` vs `a.b = function () {}`.\n     */\n    if (n.ExpressionStatement.check(path.node) &&\n        n.AssignmentExpression.check(path.node.expression) &&\n        n.MemberExpression.check(path.node.expression.left)) {\n      path = path.get('expression').get('left');\n    }\n\n    /*\n     * Same as above but for `b: c` vs `b: function () {}`.\n     */\n    if (n.Property.check(path.node) &&\n        n.Identifier.check(path.node.key)) {\n      path = path.get('key');\n    }\n\n    // Foo.bar = ...;\n    // Foo.prototype.bar = ...;\n    // Foo.bar.baz = ...;\n    if (n.MemberExpression.check(path.node)) {\n      identifiers = extractIdentifiers(path);\n      if (identifiers.length >= 2) {\n        inferMembership(identifiers.slice(0, -1));\n      }\n    }\n\n    // /** @lends Foo */{ bar: ... }\n    if (n.Identifier.check(path.node) &&\n      n.Property.check(path.parent.node) &&\n      n.ObjectExpression.check(path.parent.parent.node)) {\n      // The @lends comment is sometimes attached to the first property rather than\n      // the object expression itself.\n      identifiers = findLendsIdentifiers(path.parent.parent.node) ||\n          findLendsIdentifiers(path.parent.parent.node.properties[0]);\n      if (identifiers) {\n        inferMembership(identifiers);\n      }\n    }\n\n    // Foo = { bar: ... };\n    // Foo.prototype = { bar: ... };\n    // Foo.bar = { baz: ... };\n    if (n.Identifier.check(path.node) &&\n        n.Property.check(path.parent.node) &&\n        n.ObjectExpression.check(path.parent.parent.node) &&\n        n.AssignmentExpression.check(path.parent.parent.parent.node)) {\n      identifiers = extractIdentifiers(path.parent.parent.parent);\n      if (identifiers.length >= 1) {\n        inferMembership(identifiers);\n      }\n    }\n\n    // var Foo = { bar: ... }\n    if (n.Identifier.check(path.node) &&\n        n.Property.check(path.parent.node) &&\n        n.ObjectExpression.check(path.parent.parent.node) &&\n        n.VariableDeclarator.check(path.parent.parent.parent.node)) {\n      identifiers = [path.parent.parent.parent.node.id.name];\n      inferMembership(identifiers);\n    }\n\n    this.push(comment);\n  });\n};","path":"streams/infer_membership.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/streams/infer_membership.js#L17-L186"},"name":"inferMembership","returns":[{"title":"returns","description":"stream","type":{"type":"NameExpression","name":"Stream.Transform"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["inferMembership"]},{"description":"Create a transform stream that attempts to infer a `name` tag from the context.","tags":[{"title":"name","description":null,"name":"inferName"},{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":12,"column":0},"end":{"line":52,"column":2}},"file":"/Users/tmcw/src/documentation/streams/infer_name.js","code":"'use strict';\n\nvar through = require('through'),\n  types = require('ast-types');\n\n/**\n * Create a transform stream that attempts to infer a `name` tag from the context.\n *\n * @name inferName\n * @return {stream.Transform}\n */\nmodule.exports = function () {\n  return through(function (comment) {\n    // If this comment is already explicitly named, simply pass it\n    // through the stream without doing any inference.\n    if (comment.tags.some(function (tag) {\n      return tag.title === 'name';\n    })) {\n      this.push(comment);\n      return;\n    }\n\n    // The strategy here is to do a depth-first traversal of the AST,\n    // looking for nodes with a \"name\" property, with exceptions as needed.\n    // For example, name inference for a MemberExpression `foo.bar = baz` will\n    // infer the named based on the `property` of the MemberExpression (`bar`)\n    // rather than the `object` (`foo`).\n    types.visit(comment.context.ast, {\n      inferName: function (path, value) {\n        if (value && value.name) {\n          comment.tags.push({\n            title: 'name',\n            name: value.name\n          });\n          this.abort();\n        } else {\n          this.traverse(path);\n        }\n      },\n\n      visitNode: function (path) {\n        this.inferName(path, path.value);\n      },\n\n      visitMemberExpression: function (path) {\n        this.inferName(path, path.value.property);\n      }\n    });\n\n    this.push(comment);\n  });\n};","path":"streams/infer_name.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/streams/infer_name.js#L12-L52"},"name":"inferName","returns":[{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["inferName"]},{"description":"Detect whether a comment is a JSDoc comment: it must be a block\ncomment which starts with two asterisks, not any other number of asterisks.\n\nThe code parser automatically strips out the first asterisk that's\nrequired for the comment to be a comment at all, so we count the remaining\ncomments.","tags":[{"title":"name","description":null,"name":"isJSDocComment"},{"title":"param","description":"an ast-types node of the comment","type":{"type":"NameExpression","name":"Object"},"name":"comment"},{"title":"returns","description":"whether it is valid","type":{"type":"NameExpression","name":"boolean"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":15,"column":0},"end":{"line":18,"column":2}},"file":"/Users/tmcw/src/documentation/lib/is_jsdoc_comment.js","code":"'use strict';\n\n/**\n * Detect whether a comment is a JSDoc comment: it must be a block\n * comment which starts with two asterisks, not any other number of asterisks.\n *\n * The code parser automatically strips out the first asterisk that's\n * required for the comment to be a comment at all, so we count the remaining\n * comments.\n *\n * @name isJSDocComment\n * @param {Object} comment an ast-types node of the comment\n * @return {boolean} whether it is valid\n */\nmodule.exports = function isJSDocComment(comment) {\n  var asterisks = comment.value.match(/^(\\*+)/);\n  return comment.type === 'Block' && asterisks && asterisks[ 1 ].length === 1;\n};","path":"lib/is_jsdoc_comment.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/lib/is_jsdoc_comment.js#L15-L18"},"name":"isJSDocComment","params":[{"title":"param","description":"an ast-types node of the comment","type":{"type":"NameExpression","name":"Object"},"name":"comment"}],"returns":[{"title":"returns","description":"whether it is valid","type":{"type":"NameExpression","name":"boolean"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["isJSDocComment"]},{"description":"Create a transform stream that normalizes synonymous tags to the canonical tag type\nlisted on http://usejsdoc.org/.\n\nFor example, given the input object:\n\n    { tags: [\n      { title: \"virtual\" },\n      { title: \"return\", ... }\n    ]}\n\nThe output object will be:\n\n    { tags: [\n      { title: \"abstract\" },\n      { title: \"returns\", ... }\n    ]}\n\nThe following synonyms are normalized:\n\n * virtual -> abstract\n * extends -> augments\n * constructor -> class\n * const -> constant\n * defaultvalue -> default\n * desc -> description\n * host -> external\n * fileoverview, overview -> file\n * emits -> fires\n * func, method -> function\n * var -> member\n * arg, argument -> param\n * prop -> property\n * return -> returns\n * exception -> throws\n * linkcode, linkplain -> link","tags":[{"title":"name","description":null,"name":"normalize"},{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":46,"column":0},"end":{"line":52,"column":2}},"file":"/Users/tmcw/src/documentation/streams/normalize.js","code":"'use strict';\n\nvar through = require('through'),\n  extend = require('extend');\n\n/**\n * Create a transform stream that normalizes synonymous tags to the canonical tag type\n * listed on http://usejsdoc.org/.\n *\n * For example, given the input object:\n *\n *     { tags: [\n *       { title: \"virtual\" },\n *       { title: \"return\", ... }\n *     ]}\n *\n * The output object will be:\n *\n *     { tags: [\n *       { title: \"abstract\" },\n *       { title: \"returns\", ... }\n *     ]}\n *\n * The following synonyms are normalized:\n *\n *  * virtual -> abstract\n *  * extends -> augments\n *  * constructor -> class\n *  * const -> constant\n *  * defaultvalue -> default\n *  * desc -> description\n *  * host -> external\n *  * fileoverview, overview -> file\n *  * emits -> fires\n *  * func, method -> function\n *  * var -> member\n *  * arg, argument -> param\n *  * prop -> property\n *  * return -> returns\n *  * exception -> throws\n *  * linkcode, linkplain -> link\n *\n * @name normalize\n * @return {stream.Transform}\n */\nmodule.exports = function () {\n  return through(function (comment) {\n    this.push(extend({}, comment, {\n      tags: comment.tags.map(normalize)\n    }));\n  });\n};\n\nvar synonyms = {\n  'virtual': 'abstract',\n  'extends': 'augments',\n  'constructor': 'class',\n  'const': 'constant',\n  'defaultvalue': 'default',\n  'desc': 'description',\n  'host': 'external',\n  'fileoverview': 'file',\n  'overview': 'file',\n  'emits': 'fires',\n  'func': 'function',\n  'method': 'function',\n  'var': 'member',\n  'arg': 'param',\n  'argument': 'param',\n  'prop': 'property',\n  'return': 'returns',\n  'exception': 'throws',\n  'linkcode': 'link',\n  'linkplain': 'link'\n};\n\nfunction normalize(tag) {\n  var canonical = synonyms[tag.title];\n  return canonical ? extend({}, tag, { title: canonical }) : tag;\n}","path":"streams/normalize.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/streams/normalize.js#L46-L52"},"name":"normalize","returns":[{"title":"returns","description":null,"type":{"type":"NameExpression","name":"stream.Transform"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["normalize"]},{"description":"Documentation stream parser: this receives a module-dep item,\nreads the file, parses the JavaScript, parses the JSDoc, and\nemits parsed comments.","tags":[{"title":"name","description":null,"name":"parse"},{"title":"param","description":"a chunk of data provided by module-deps","type":{"type":"NameExpression","name":"Object"},"name":"data"},{"title":"returns","description":"this emits data","type":{"type":"UndefinedLiteral"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":83,"column":0},"end":{"line":134,"column":2}},"file":"/Users/tmcw/src/documentation/streams/parse.js","code":"'use strict';\n\nvar doctrine = require('doctrine'),\n  espree = require('espree'),\n  through = require('through'),\n  types = require('ast-types'),\n  extend = require('extend'),\n  isJSDocComment = require('../lib/is_jsdoc_comment');\n\n/**\n * Comment-out a shebang line that may sit at the top of a file,\n * making it executable on linux-like systems.\n * @param {String} code the source code in full\n * @return {String} code\n * @example\n * var foo = commentShebang('#!/usr/bin/env/node');\n * foo === '//#!/usr/bin/env/node';\n */\nfunction commentShebang(code) {\n  return (code[0] === '#' && code[1] === '!') ? '//' + code : code;\n}\n\nvar espreeConfig = {\n  loc: true,\n  attachComment: true,\n  // specify parsing features (default only has blockBindings: true)\n    ecmaFeatures: {\n        // enable parsing of arrow functions\n        arrowFunctions: true,\n        // enable parsing of let/const\n        blockBindings: true,\n        // enable parsing of destructured arrays and objects\n        destructuring: true,\n        // enable parsing of regular expression y flag\n        regexYFlag: true,\n        // enable parsing of regular expression u flag\n        regexUFlag: true,\n        // enable parsing of template strings\n        templateStrings: true,\n        // enable parsing of binary literals\n        binaryLiterals: true,\n        // enable parsing of ES6 octal literals\n        octalLiterals: true,\n        // enable parsing unicode code point escape sequences\n        unicodeCodePointEscapes: true,\n        // enable parsing of default parameters\n        defaultParams: true,\n        // enable parsing of rest parameters\n        restParams: true,\n        // enable parsing of for-of statement\n        forOf: true,\n        // enable parsing computed object literal properties\n        objectLiteralComputedProperties: true,\n        // enable parsing of shorthand object literal methods\n        objectLiteralShorthandMethods: true,\n        // enable parsing of shorthand object literal properties\n        objectLiteralShorthandProperties: true,\n        // Allow duplicate object literal properties (except '__proto__')\n        objectLiteralDuplicateProperties: true,\n        // enable parsing of generators/yield\n        generators: true,\n        // enable parsing spread operator\n        spread: true,\n        // enable parsing classes\n        classes: true,\n        // enable parsing of modules\n        modules: true,\n        // enable React JSX parsing\n        jsx: true,\n        // enable return in global scope\n        globalReturn: true\n    }\n};\n\n/**\n * Documentation stream parser: this receives a module-dep item,\n * reads the file, parses the JavaScript, parses the JSDoc, and\n * emits parsed comments.\n * @name parse\n * @param {Object} data a chunk of data provided by module-deps\n * @return {undefined} this emits data\n */\nmodule.exports = function () {\n  return through(function (data) {\n    try {\n      var code = commentShebang(data.source),\n        ast = espree.parse(code, espreeConfig),\n        stream = this;\n    } catch(e) {\n      e.message += ' (' + data.file + ')';\n      this.emit('error', e);\n      this.emit('end');\n    }\n\n    types.visit(ast, {\n      visitNode: function (path) {\n        /**\n         * Parse a comment with doctrine and decorate the result with file position and code context.\n         *\n         * @param {Object} comment the current state of the parsed JSDoc comment\n         * @return {undefined} this emits data\n         */\n        function parseComment(comment) {\n          var parsedComment = doctrine.parse(comment.value, { unwrap: true });\n\n          parsedComment.context = {\n            loc: extend({}, path.value.loc),\n            file: data.file\n          };\n\n          // This is non-enumerable so that it doesn't get stringified in output; e.g. by the\n          // documentation binary.\n          Object.defineProperty(parsedComment.context, 'ast', {\n            enumerable: false,\n            value: path\n          });\n\n          if (path.parent && path.parent.node) {\n            parsedComment.context.code = code.substring\n              .apply(code, path.parent.node.range);\n          }\n\n          stream.push(parsedComment);\n        }\n\n        (path.value.leadingComments || [])\n          .filter(isJSDocComment)\n          .forEach(parseComment);\n\n        this.traverse(path);\n      }\n    });\n  });\n};","path":"streams/parse.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/streams/parse.js#L83-L134"},"name":"parse","params":[{"title":"param","description":"a chunk of data provided by module-deps","type":{"type":"NameExpression","name":"Object"},"name":"data"}],"returns":[{"title":"returns","description":"this emits data","type":{"type":"UndefinedLiteral"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["parse"]},{"description":"Parse a comment with doctrine and decorate the result with file position and code context.","tags":[{"title":"param","description":"the current state of the parsed JSDoc comment","type":{"type":"NameExpression","name":"Object"},"name":"comment"},{"title":"returns","description":"this emits data","type":{"type":"UndefinedLiteral"}},{"title":"name","name":"parseComment"}],"context":{"loc":{"start":{"line":103,"column":8},"end":{"line":124,"column":9}},"file":"/Users/tmcw/src/documentation/streams/parse.js","code":"{\n        /**\n         * Parse a comment with doctrine and decorate the result with file position and code context.\n         *\n         * @param {Object} comment the current state of the parsed JSDoc comment\n         * @return {undefined} this emits data\n         */\n        function parseComment(comment) {\n          var parsedComment = doctrine.parse(comment.value, { unwrap: true });\n\n          parsedComment.context = {\n            loc: extend({}, path.value.loc),\n            file: data.file\n          };\n\n          // This is non-enumerable so that it doesn't get stringified in output; e.g. by the\n          // documentation binary.\n          Object.defineProperty(parsedComment.context, 'ast', {\n            enumerable: false,\n            value: path\n          });\n\n          if (path.parent && path.parent.node) {\n            parsedComment.context.code = code.substring\n              .apply(code, path.parent.node.range);\n          }\n\n          stream.push(parsedComment);\n        }\n\n        (path.value.leadingComments || [])\n          .filter(isJSDocComment)\n          .forEach(parseComment);\n\n        this.traverse(path);\n      }","path":"streams/parse.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/streams/parse.js#L103-L124"},"params":[{"title":"param","description":"the current state of the parsed JSDoc comment","type":{"type":"NameExpression","name":"Object"},"name":"comment"}],"returns":[{"title":"returns","description":"this emits data","type":{"type":"UndefinedLiteral"}}],"name":"parseComment","members":{"instance":[],"static":[]},"path":["parseComment"]},{"description":"Create a stream.Transform that sorts its input of comments\nby the name tag, if any, and otherwise by filename.","tags":[{"title":"name","description":null,"name":"sort"},{"title":"returns","description":"a transform stream","type":{"type":"NameExpression","name":"stream.Transform"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":9,"column":0},"end":{"line":23,"column":2}},"file":"/Users/tmcw/src/documentation/streams/sort.js","code":"var sort = require('sort-stream');\n\n/**\n * Create a stream.Transform that sorts its input of comments\n * by the name tag, if any, and otherwise by filename.\n * @name sort\n * @return {stream.Transform} a transform stream\n */\nmodule.exports = function () {\n\n  function getSortKey(comment) {\n    for (var i = 0; i < comment.tags.length; i++) {\n      if (comment.tags[i].title === 'name') {\n        return comment.tags[i].name;\n      }\n    }\n    return comment.context.file;\n  }\n\n  return sort(function (a, b) {\n    return getSortKey(a) > getSortKey(b);\n  });\n};","path":"streams/sort.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/streams/sort.js#L9-L23"},"name":"sort","returns":[{"title":"returns","description":"a transform stream","type":{"type":"NameExpression","name":"stream.Transform"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["sort"]},{"description":"Generate JavaScript documentation as a list of parsed JSDoc\ncomments, given a root file as a path.","tags":[{"title":"name","description":null,"name":"documentation"},{"title":"param","description":"files to process","type":{"type":"UnionType","elements":[{"type":"TypeApplication","expression":{"type":"NameExpression","name":"Array"},"applications":[{"type":"NameExpression","name":"String"}]},{"type":"NameExpression","name":"String"}]},"name":"indexes"},{"title":"param","description":"options","type":{"type":"NameExpression","name":"Object"},"name":"options"},{"title":"returns","description":"stream of output","type":{"type":"NameExpression","name":"Object"}},{"title":"memberof","description":"module"},{"title":"static"}],"context":{"loc":{"start":{"line":29,"column":0},"end":{"line":66,"column":2}},"file":"/Users/tmcw/src/documentation/index.js","code":"'use strict';\n\nvar mdeps = require('module-deps'),\n  path = require('path'),\n  PassThrough = require('stream').PassThrough,\n  flatten = require('./streams/flatten.js'),\n  sort = require('./streams/sort'),\n  normalize = require('./streams/normalize.js'),\n  filterAccess = require('./streams/filter_access.js'),\n  parse = require('./streams/parse'),\n  inferName = require('./streams/infer_name'),\n  inferKind = require('./streams/infer_kind'),\n  inferMembership = require('./streams/infer_membership');\n\n// Skip external modules. Based on http://git.io/pzPO.\nvar externalModuleRegexp = process.platform === 'win32' ?\n  /^(\\.|\\w:)/ :\n  /^[\\/.]/;\n\n/**\n * Generate JavaScript documentation as a list of parsed JSDoc\n * comments, given a root file as a path.\n *\n * @name documentation\n * @param {Array<String>|String} indexes files to process\n * @param {Object} options options\n * @return {Object} stream of output\n */\nmodule.exports = function (indexes, options) {\n  options = options || options;\n\n  var md = mdeps({\n    filter: function (id) {\n      return externalModuleRegexp.test(id);\n    }\n  });\n\n  if (typeof indexes === 'string') {\n    indexes = [indexes];\n  }\n\n  indexes.forEach(function (index) {\n    md.write(path.resolve(index));\n  });\n  md.end();\n\n  var end = new PassThrough({ objectMode: true });\n\n  function deferErrors(stream) {\n    return stream.on('error', function (a, b, c) {\n      end.emit('error', a, b, c);\n      end.emit('end');\n    });\n  }\n\n  return md\n    .pipe(deferErrors(parse()))\n    .pipe(deferErrors(inferName()))\n    .pipe(sort())\n    .pipe(deferErrors(inferKind()))\n    .pipe(deferErrors(inferMembership()))\n    .pipe(normalize())\n    .pipe(flatten())\n    .pipe(filterAccess(options.private ? [] : undefined))\n    .pipe(end);\n};","path":"index.js","github":"https://github.com/documentationjs/documentation/blob/b71901ff40c8db36a5b02530c18c3e65ad6295f1/index.js#L29-L66"},"name":"documentation","params":[{"title":"param","description":"files to process","type":{"type":"UnionType","elements":[{"type":"TypeApplication","expression":{"type":"NameExpression","name":"Array"},"applications":[{"type":"NameExpression","name":"String"}]},{"type":"NameExpression","name":"String"}]},"name":"indexes"},{"title":"param","description":"options","type":{"type":"NameExpression","name":"Object"},"name":"options"}],"returns":[{"title":"returns","description":"stream of output","type":{"type":"NameExpression","name":"Object"}}],"memberof":"module","scope":"static","members":{"instance":[],"static":[]},"path":["documentation"]}]

index.js

@@ -6,3 +6,6 @@ 'use strict';
   PassThrough = require('stream').PassThrough,
+  flatten = require('./streams/flatten.js'),
   sort = require('./streams/sort'),
+  normalize = require('./streams/normalize.js'),
+  filterAccess = require('./streams/filter_access.js'),
   parse = require('./streams/parse'),
@@ -24,5 +27,8 @@ inferName = require('./streams/infer_name'),
  * @param {Array<String>|String} indexes files to process
+ * @param {Object} options options
  * @return {Object} stream of output
  */
-module.exports = function (indexes) {
+module.exports = function (indexes, options) {
+  options = options || {};
+
   var md = mdeps({
@@ -58,3 +64,6 @@ filter: function (id) {
     .pipe(deferErrors(inferMembership()))
+    .pipe(normalize())
+    .pipe(flatten())
+    .pipe(filterAccess(options.private ? [] : undefined))
     .pipe(end);
 };

package.json

 {
   "name": "documentation",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "a documentation generator",
@@ -5,0 +5,0 @@ "main": "index.js",

streams/filter_access.js

@@ -10,5 +10,5 @@ 'use strict';
  *
+ * @name access
  * @public
  * @param {Array<String>} [levels=[private]] excluded access levels.
- * @name access
  * @return {stream.Transform}
@@ -15,0 +15,0 @@ */

streams/output/html.js

@@ -13,2 +13,13 @@ 'use strict';
 
+/**
+ * Make slugg a unary so we can use it in functions
+ *
+ * @private
+ * @param {string} input text
+ * @returns {string} output
+ */
+function slug(p) {
+  return slugg(p);
+}
+
 var BUILTINS = [
@@ -175,3 +186,3 @@ 'Array',
     var paths = comments.map(function (comment) {
-      return comment.path.map(slugg).join('/');
+      return comment.path.map(slug).join('/');
     }).filter(function (path) {
@@ -186,3 +197,3 @@ return path;
     Handlebars.registerHelper('permalink', function () {
-      return this.path.map(slugg).join('/');
+      return this.path.map(slug).join('/');
     });
@@ -196,4 +207,4 @@
     function autolink(text) {
-      if (paths.indexOf(slugg(text)) !== -1) {
-        return '<a href="#' + slugg(text) + '">' + text + '</a>';
+      if (paths.indexOf(slug(text)) !== -1) {
+        return '<a href="#' + slug(text) + '">' + text + '</a>';
       } else if (BUILTINS[text.toLowerCase()]) {
@@ -200,0 +211,0 @@ return '<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/' + text + '">' + text + '</a>';

No alert changes

Worsened metrics

Total package byte prevSize

596612

decreased by-26.45%

Number of package files

56

decreased by-32.53%

Lines of code

5879

decreased by-5.89%

No dependency changes