Add --access flag. Fixes #262

Author: tmcw

bin/documentation.js

@@ -51,6 +51,13 @@ function parseArgs() {
       default: false,
       alias: 'p'
     })
+    .option('access', {
+      describe: 'Include only comments with a given access level, out of private, ' +
+        'protected, public, undefined. By default, public, protected, and undefined access ' +
+        'levels are included',
+      choices: ['public', 'private', 'protected', 'undefined'],
+      alias: 'a'
+    })
     .option('github', {
       type: 'boolean',
       describe: 'infer links to github in documentation',
@@ -64,6 +71,14 @@ function parseArgs() {
   }
   options = extend(options, argv);
 
+  if (typeof options.access === 'string') {
+    options.access = [options.access];
+  }
+
+  if (options.private) {
+    options.access = (options.access || ['public', 'undefined', 'protected']).concat(['private']);
+  }
+
   var command = argv._[0],
     inputs = argv._.slice(1);
 

index.js

@@ -57,7 +57,7 @@ function expandInputs(indexes, options, callback) {
  * Generate JavaScript documentation as a list of parsed JSDoc
  * comments, given a root file as a path.
  *
- * @name documentation
+ * @alias documentation
  * @param {Array<string>|string} indexes files to process
  * @param {Object} options options
  * @param {Array<string>} options.external a string regex / glob match pattern
@@ -70,6 +70,8 @@ function expandInputs(indexes, options, callback) {
  * even in JavaScript code. With the polyglot option set, this has no effect.
  * @param {Array<string|Object>} [options.order=[]] optional array that
  * defines sorting order of documentation
+ * @param {Array<string>} [options.access=[]] an array of access levels
+ * to output in documentation
  * @param {Object} [options.hljs] hljs optional options
  * @param {boolean} [options.hljs.highlightAuto=false] hljs automatically detect language
  * @param {Array} [options.hljs.languages] languages for hljs to choose from
@@ -85,6 +87,10 @@ module.exports = function (indexes, options, callback) {
     indexes = [indexes];
   }
 
+  if (!options.access) {
+    options.access = ['public', 'undefined', 'protected'];
+  }
+
   var parseFn = (options.polyglot) ? polyglot : parseJavaScript;
 
   return expandInputs(indexes, options, function (error, inputs) {
@@ -93,8 +99,7 @@ module.exports = function (indexes, options, callback) {
     }
     try {
       callback(null,
-        filterAccess(
-          options.private ? [] : undefined,
+        filterAccess(options.access,
           hierarchy(
             inputs
               .filter(filterJS(options.extension))

lib/commands/build.js

@@ -117,4 +117,3 @@ function addOutputArgs(yargs) {
   })
   .help('help');
 }
-

lib/commands/index.js

@@ -14,4 +14,3 @@ module.exports = {
   'serve': require('./serve'),
   'lint': require('./lint')
 };
-

lib/filter_access.js

@@ -7,16 +7,15 @@ var walk = require('./walk');
  * users to write documentation for non-public members by using the
  * `@private` tag.
  *
- * @public
- * @param {Array<string>} [levels=['private']] excluded access levels.
+ * @param {Array<string>} [levels=['public', 'undefined', 'protected']] included access levels.
  * @param {Array<Object>} comments parsed comments (can be nested)
  * @return {Array<Object>} filtered comments
  */
 function filterAccess(levels, comments) {
-  levels = levels || ['private'];
+  levels = levels || ['public', 'undefined', 'protected'];
 
   function filter(comment) {
-    return levels.indexOf(comment.access) === -1;
+    return levels.indexOf(String(comment.access)) !== -1;
   }
 
   function recurse(comment) {

test/bin.js

@@ -189,6 +189,22 @@ test('with an invalid command', function (t) {
   });
 }, options);
 
+test('--access flag', function (t) {
+  documentation(['build --shallow fixture/internal.input.js -a public'], {}, function (err, data) {
+    t.error(err);
+    t.equal(data, '[]');
+    t.end();
+  }, false);
+});
+
+test('--private flag', function (t) {
+  documentation(['build fixture/internal.input.js --private'], {}, function (err, data) {
+    t.error(err);
+    t.ok(data.length > 2, 'outputs docs');
+    t.end();
+  }, false);
+});
+
 test('write to file', function (t) {
 
   var dst = path.join(os.tmpdir(), (Date.now() + Math.random()).toString());

test/lib/filter_access.js

@@ -3,24 +3,39 @@
 var test = require('tap').test,
   filterAccess = require('../../lib/filter_access');
 
-test('filterAccess default', function (t) {
-  t.deepEqual(filterAccess(null, [{
+test('filterAccess public, protected, undefined, no private', function (t) {
+  t.deepEqual(filterAccess(['public', 'protected', 'undefined'], [{
+    access: 'public'
+  }, {
+    access: 'protected'
+  }, {
+    foo: 2
+  }, {
     access: 'private'
-  }]), []);
+  }]), [{
+    access: 'public'
+  }, {
+    access: 'protected'
+  }, {
+    foo: 2
+  }]);
   t.end();
 });
 
-test('filterAccess public', function (t) {
-  t.deepEqual(filterAccess(null, [{
-    access: 'public'
-  }]), [{
+test('filterAccess explicit public', function (t) {
+  t.deepEqual(filterAccess(['public'], [
+    { access: 'public' },
+    { access: 'protected' },
+    { foo: 2 },
+    { access: 'private' }]),
+  [{
     access: 'public'
   }]);
   t.end();
 });
 
 test('filterAccess override', function (t) {
-  t.deepEqual(filterAccess([], [{
+  t.deepEqual(filterAccess(['private'], [{
     access: 'private'
   }]), [{
     access: 'private'
@@ -29,7 +44,7 @@ test('filterAccess override', function (t) {
 });
 
 test('filterAccess nesting', function (t) {
-  t.deepEqual(filterAccess(null, [{
+  t.deepEqual(filterAccess(['public', 'protected', 'undefined'], [{
     access: 'public',
     members: {
       static: [{