Graduate access and flattening to the default

bin/documentation.js

@@ -17,10 +17,7 @@ var documentation = require('../'),
   docset = require('../streams/output/docset.js'),
 
   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');
 
 var yargs = require('yargs')
   .usage('Usage: $0 <command> [options]')
@@ -108,12 +105,11 @@ if (argv.f === 'html' && argv.o === 'stdout') {
   throw new Error('The HTML output mode requires a destination directory set with -o');
 }
 
-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);
 
 if (argv.o !== 'stdout') {

index.js

@@ -3,7 +3,10 @@
 var mdeps = require('module-deps'),
   path = require('path'),
   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'),
   inferName = require('./streams/infer_name'),
   inferKind = require('./streams/infer_kind'),
@@ -20,9 +23,12 @@ var externalModuleRegexp = process.platform === 'win32' ?
  *
  * @name documentation
  * @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({
     filter: function (id) {
       return externalModuleRegexp.test(id);
@@ -53,5 +59,8 @@ module.exports = function (indexes) {
     .pipe(sort())
     .pipe(deferErrors(inferKind()))
     .pipe(deferErrors(inferMembership()))
+    .pipe(normalize())
+    .pipe(flatten())
+    .pipe(filterAccess(options.private ? [] : undefined))
     .pipe(end);
 };

streams/filter_access.js

@@ -7,9 +7,9 @@ var through = require('through');
  * users to write documentation for non-public members by using the
  * `@private` tag.
  *
+ * @name access
  * @public
  * @param {Array<String>} [levels=[private]] excluded access levels.
- * @name access
  * @return {stream.Transform}
  */
 module.exports = function (levels) {

streams/output/html.js

@@ -10,6 +10,17 @@ var through = require('through'),
   Handlebars = require('handlebars'),
   extend = require('extend');
 
+/**
+ * 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 = [
   'Array',
   'ArrayBuffer',
@@ -171,7 +182,7 @@ module.exports = function (opts) {
     }
 
     var paths = comments.map(function (comment) {
-      return comment.path.map(slugg).join('/');
+      return comment.path.map(slug).join('/');
     }).filter(function (path) {
       return path;
     });
@@ -181,7 +192,7 @@ module.exports = function (opts) {
     });
 
     Handlebars.registerHelper('permalink', function () {
-      return this.path.map(slugg).join('/');
+      return this.path.map(slug).join('/');
     });
 
     /**
@@ -190,8 +201,8 @@ module.exports = function (opts) {
      * @returns {string} potentially linked HTML
      */
     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()]) {
         return '<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/' + text + '">' + text + '</a>';
       }

test/fixture/_multi-file-input.json

@@ -35,7 +35,20 @@
       },
       "file": "fixture/simple.input.js",
       "code": "module.exports = function () {\n  // this returns 1\n  return 1;\n};"
-    }
+    },
+    "returns": [
+      {
+        "title": "returns",
+        "description": "numberone",
+        "type": {
+          "type": "NameExpression",
+          "name": "Number"
+        }
+      }
+    ],
+    "name": "exports",
+    "memberof": "module",
+    "scope": "static"
   },
   {
     "description": "This function returns the number plus two.",
@@ -79,6 +92,31 @@
       },
       "file": "fixture/simple-two.input.js",
       "code": "function returnTwo(a) {\n  // this returns a + 2\n  return a + 2;\n}"
-    }
+    },
+    "params": [
+      {
+        "title": "param",
+        "description": "the number",
+        "type": {
+          "type": "NameExpression",
+          "name": "Number"
+        },
+        "name": "a"
+      }
+    ],
+    "returns": [
+      {
+        "title": "returns",
+        "description": "numbertwo",
+        "type": {
+          "type": "NameExpression",
+          "name": "Number"
+        }
+      }
+    ],
+    "examples": [
+      "var result = returnTwo(4);\n// result is 6"
+    ],
+    "name": "returnTwo"
   }
 ]

test/fixture/es6.output.json

@@ -28,6 +28,17 @@
       },
       "file": "fixture/es6.input.js",
       "code": "var multiply = (a, b) => a * b;\nmodule.exports = multiply;"
-    }
+    },
+    "returns": [
+      {
+        "title": "returns",
+        "description": "numberone",
+        "type": {
+          "type": "NameExpression",
+          "name": "Number"
+        }
+      }
+    ],
+    "name": "multiply"
   }
 ]

test/fixture/simple-hashbang.output.json

@@ -35,6 +35,19 @@
       },
       "file": "fixture/simple-hashbang.input.js",
       "code": "module.exports = function () {\n  // this returns 1\n  return 1;\n};"
-    }
+    },
+    "returns": [
+      {
+        "title": "returns",
+        "description": "numberone",
+        "type": {
+          "type": "NameExpression",
+          "name": "Number"
+        }
+      }
+    ],
+    "name": "exports",
+    "memberof": "module",
+    "scope": "static"
   }
 ]

test/fixture/simple-private.output.json

@@ -1,47 +1 @@
-[
-  {
-    "description": "This function returns the number plus two.",
-    "tags": [
-      {
-        "title": "param",
-        "description": "the number",
-        "type": {
-          "type": "NameExpression",
-          "name": "Number"
-        },
-        "name": "a"
-      },
-      {
-        "title": "returns",
-        "description": "numbertwo",
-        "type": {
-          "type": "NameExpression",
-          "name": "Number"
-        }
-      },
-      {
-        "title": "private",
-        "description": null,
-        "type": null
-      },
-      {
-        "title": "name",
-        "name": "returnTwo"
-      }
-    ],
-    "context": {
-      "loc": {
-        "start": {
-          "line": 8,
-          "column": 0
-        },
-        "end": {
-          "line": 11,
-          "column": 1
-        }
-      },
-      "file": "fixture/simple-private.input.js",
-      "code": "function returnTwo(a) {\n  // this returns a + 2\n  return a + 2;\n}"
-    }
-  }
-]
+[]

test/fixture/simple-two.output.json

@@ -41,6 +41,31 @@
       },
       "file": "fixture/simple-two.input.js",
       "code": "function returnTwo(a) {\n  // this returns a + 2\n  return a + 2;\n}"
-    }
+    },
+    "params": [
+      {
+        "title": "param",
+        "description": "the number",
+        "type": {
+          "type": "NameExpression",
+          "name": "Number"
+        },
+        "name": "a"
+      }
+    ],
+    "returns": [
+      {
+        "title": "returns",
+        "description": "numbertwo",
+        "type": {
+          "type": "NameExpression",
+          "name": "Number"
+        }
+      }
+    ],
+    "examples": [
+      "var result = returnTwo(4);\n// result is 6"
+    ],
+    "name": "returnTwo"
   }
 ]

test/fixture/simple.output.json

@@ -35,6 +35,19 @@
       },
       "file": "fixture/simple.input.js",
       "code": "module.exports = function () {\n  // this returns 1\n  return 1;\n};"
-    }
+    },
+    "returns": [
+      {
+        "title": "returns",
+        "description": "numberone",
+        "type": {
+          "type": "NameExpression",
+          "name": "Number"
+        }
+      }
+    ],
+    "name": "exports",
+    "memberof": "module",
+    "scope": "static"
   }
 ]

test/test.js

@@ -3,8 +3,6 @@
 var test = require('prova'),
   documentation = require('../'),
   markdown = require('../streams/output/markdown.js'),
-  flatten = require('../streams/flatten.js'),
-  filterAccess = require('../streams/filter_access.js'),
   hierarchy = require('../streams/hierarchy.js'),
   outputHtml = require('../streams/output/html.js'),
   glob = require('glob'),
@@ -60,8 +58,6 @@ test('html', function (tt) {
   glob.sync(path.join(__dirname, 'fixture/html', '*.input.js')).forEach(function (file) {
     tt.test(path.basename(file), function (t) {
       documentation([file])
-        .pipe(flatten())
-        .pipe(filterAccess())
         .pipe(hierarchy())
         .pipe(outputHtml())
         .pipe(concat(function (result) {
@@ -83,8 +79,6 @@ test('markdown', function (tt) {
   glob.sync(path.join(__dirname, 'fixture', '*.input.js')).forEach(function (file) {
     tt.test(path.basename(file), function (t) {
       documentation([file])
-        .pipe(flatten())
-        .pipe((filterAccess()))
         .pipe(markdown())
         .pipe(concat(function (result) {
         var outputfile = file.replace('.input.js', '.output.md');
@@ -96,8 +90,6 @@ test('markdown', function (tt) {
     });
     tt.test(path.basename(file) + ' custom', function (t) {
       documentation([file])
-        .pipe(flatten())
-        .pipe((filterAccess()))
         .pipe(markdown({
           template: path.join(__dirname, '/misc/custom.hbs')
         }))