Access inheritance (fixes #78)

Author: jfirebaugh

CHANGELOG.md

@@ -58,6 +58,10 @@ Parent.Child = function () {};
 Parent.Child.Grandchild = function () {};
 ```
 
+In addition, filtering by access is now applied to the entire hierarchy: if you
+mark a class as `@private`, neither it nor its children will be included in the
+output by default, regardless of the access specifiers of the children.
+
 **mdast-based Markdown output**
 
 We've switched from templating Markdown output with [Handlebars.js](http://handlebarsjs.com/)

index.js

@@ -82,25 +82,27 @@ module.exports = function (indexes, options, callback) {
       return callback(error);
     }
     try {
-      var flat = inputs
-        .filter(filterJS)
-        .reduce(function (memo, file) {
-          return memo.concat(parseFn(file));
-        }, [])
-        .map(pipeline(
-          lint,
-          inferName(),
-          inferKind(),
-          inferParams(),
-          inferReturn(),
-          inferMembership(),
-          nestParams,
-          options.github ? github : noop
-        ))
-        .filter(Boolean)
-        .sort(sort.bind(undefined, options.order))
-        .filter(filterAccess.bind(undefined, options.private ? [] : undefined))
-      callback(null, options.hierarchy !== false ? hierarchy(flat) : flat);
+      callback(null,
+        filterAccess(
+          options.private ? [] : undefined,
+          hierarchy(
+            inputs
+              .filter(filterJS)
+              .reduce(function (memo, file) {
+                return memo.concat(parseFn(file));
+              }, [])
+              .map(pipeline(
+                lint,
+                inferName(),
+                inferKind(),
+                inferParams(),
+                inferReturn(),
+                inferMembership(),
+                nestParams,
+                options.github ? github : noop
+              ))
+              .filter(Boolean)
+              .sort(sort.bind(undefined, options.order)))));
     } catch (e) {
       callback(e);
     }

lib/filter_access.js

@@ -1,17 +1,30 @@
 'use strict';
 
+var walk = require('./walk');
+
 /**
  * Exclude given access levels from the generated documentation: this allows
  * users to write documentation for non-public members by using the
  * `@private` tag.
  *
  * @name access
  * @public
- * @param {Array<string>} [levels=[private]] excluded access levels.
- * @param {Object} comment a parsed comment
- * @return {boolean} whether the comment should be output
+ * @param {Array<string>} [levels=['private']] excluded access levels.
+ * @param {Array<Object>} comments parsed comments (can be nested)
+ * @return {Array<Object>} filtered comments
  */
-module.exports = function (levels, comment) {
+module.exports = function (levels, comments) {
   levels = levels || ['private'];
-  return levels.indexOf(comment.access) === -1;
+
+  function filter(comment) {
+    return levels.indexOf(comment.access) === -1;
+  }
+
+  function recurse(comment) {
+    for (var scope in comment.members) {
+      comment.members[scope] = comment.members[scope].filter(filter);
+    }
+  }
+
+  return walk(comments.filter(filter), recurse);
 };

lib/walk.js

@@ -8,10 +8,10 @@
  */
 function walk(comments, fn) {
   comments.forEach(function (comment) {
+    fn(comment);
     for (var scope in comment.members) {
       walk(comment.members[scope], fn);
     }
-    fn(comment);
   });
   return comments;
 }

test/lib/filter_access.js

@@ -4,22 +4,56 @@ var test = require('tap').test,
   filterAccess = require('../../lib/filter_access');
 
 test('filterAccess default', function (t) {
-  t.equal(filterAccess(null, {
+  t.deepEqual(filterAccess(null, [{
     access: 'private'
-  }), false);
+  }]), []);
   t.end();
 });
 
 test('filterAccess public', function (t) {
-  t.equal(filterAccess(null, {
+  t.deepEqual(filterAccess(null, [{
     access: 'public'
-  }), true);
+  }]), [{
+    access: 'public'
+  }]);
   t.end();
 });
 
 test('filterAccess override', function (t) {
-  t.equal(filterAccess([], {
+  t.deepEqual(filterAccess([], [{
+    access: 'private'
+  }]), [{
     access: 'private'
-  }), true);
+  }]);
+  t.end();
+});
+
+test('filterAccess nesting', function (t) {
+  t.deepEqual(filterAccess(null, [{
+    access: 'public',
+    members: {
+      static: [{
+        access: 'public'
+      }, {
+        access: 'private'
+      }]
+    }
+  }, {
+    access: 'private',
+    members: {
+      static: [{
+        access: 'public'
+      }, {
+        access: 'private'
+      }]
+    }
+  }]), [{
+    access: 'public',
+    members: {
+      static: [{
+        access: 'public'
+      }]
+    }
+  }]);
   t.end();
 });