Merge pull request #441 from arv/infer-private

Add support for inferring private based on the name

Author: tmcw

docs/USAGE.md

@@ -19,27 +19,40 @@ Commands:
   readme  inject documentation into your README.md
 
 Options:
-  --help           Show help                                           [boolean]
-  --version        Show version number                                 [boolean]
-  --shallow        shallow mode turns off dependency resolution, only processing
-                   the specified files (or the main script specified in
-                   package.json)                      [boolean] [default: false]
-  --config, -c     configuration file. an array defining explicit sort order
-  --external       a string / glob match pattern that defines which external
-                   modules will be whitelisted and included in the generated
-                   documentation.                                [default: null]
-  --extension, -e  only input source files matching this extension will be
-                   parsed, this option can be used multiple times.
-  --polyglot       polyglot mode turns off dependency resolution and enables
-                   multi-language support. use this to document c++    [boolean]
-  --private, -p    generate documentation tagged as private
+  --help             Show help                                         [boolean]
+  --version          Show version number                               [boolean]
+  --shallow          shallow mode turns off dependency resolution, only
+                     processing the specified files (or the main script
+                     specified in package.json)       [boolean] [default: false]
+  --config, -c       configuration file. an array defining explicit sort order
+  --external         a string / glob match pattern that defines which external
+                     modules will be whitelisted and included in the generated
+                     documentation.                              [default: null]
+  --extension, -e    only input source files matching this extension will be
+                     parsed, this option can be used multiple times.
+  --polyglot         polyglot mode turns off dependency resolution and enables
+                     multi-language support. use this to document c++  [boolean]
+  --private, -p      generate documentation tagged as private
                                                       [boolean] [default: false]
-  --access, -a     Include only comments with a given access level, out of
-                   private, protected, public, undefined. By default, public,
-                   protected, and undefined access levels are included
+  --access, -a       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"]
-  --github, -g     infer links to github in documentation              [boolean]
+  --github, -g       infer links to github in documentation            [boolean]
+  --infer-private    Infer private access based on the name. This is a regular
+                     expression that is used to match the name          [string]
+  --theme, -t        specify a theme: this must be a valid theme module
+  --name             project name. by default, inferred from package.json
+  --watch, -w        watch input files and rebuild documentation when they
+                     change                                            [boolean]
+  --project-version  project version. by default, inferred from package.json
+  --output, -o       output location. omit for stdout, otherwise is a filename
+                     for single-file outputs and a directory name for multi-file
+                     outputs like html                       [default: "stdout"]
+  --format, -f                 [choices: "json", "md", "html"] [default: "json"]
 
 Examples:
-  documentation build foo.js  parse documentation in a given file
+  documentation build foo.js -f md >        parse documentation in a file and
+  API.md                                    generate API documentation as
+                                            Markdown
 ```

index.js

@@ -18,6 +18,7 @@ var fs = require('fs'),
   inferProperties = require('./lib/infer/properties'),
   inferMembership = require('./lib/infer/membership'),
   inferReturn = require('./lib/infer/return'),
+  inferAccess = require('./lib/infer/access'),
   formatLint = require('./lib/lint').formatLint,
   lintComments = require('./lib/lint').lintComments;
 
@@ -150,6 +151,7 @@ function buildSync(indexes, options) {
         }, [])
         .map(pipeline(
           inferName(),
+          inferAccess(options.inferPrivate),
           inferAugments(),
           inferKind(),
           inferParams(),
@@ -205,6 +207,7 @@ module.exports.lint = function lint(indexes, options, callback) {
           .map(pipeline(
             lintComments,
             inferName(),
+            inferAccess(options.inferPrivate),
             inferAugments(),
             inferKind(),
             inferParams(),

lib/commands/shared_options.js

@@ -48,6 +48,11 @@ function sharedInputOptions(parser) {
     type: 'boolean',
     describe: 'infer links to github in documentation',
     alias: 'g'
+  })
+  .option('infer-private', {
+    type: 'string',
+    describe: 'Infer private access based on the name. This is a regular expression that ' +
+      'is used to match the name'
   });
 }
 

lib/infer/access.js

@@ -0,0 +1,24 @@
+'use strict';
+
+var shouldSkipInference = require('./should_skip_inference');
+
+module.exports = function (pattern) {
+  var re = pattern && new RegExp(pattern);
+
+  /**
+   * Infers access (only private atm) from the name.
+   *
+   * @name inferAccess
+   * @param {Object} comment parsed comment
+   * @returns {Object} comment with access inferred
+   */
+  return shouldSkipInference(function inferAccess(comment) {
+    // This needs to run after inferName beacuse we infer the access based on
+    // the name.
+    if (re && comment.name && comment.access === undefined && re.test(comment.name)) {
+      comment.access = 'private';
+    }
+
+    return comment;
+  });
+};

test/bin.js

@@ -228,6 +228,23 @@ test('--private flag', function (t) {
   }, false);
 });
 
+test('--infer-private flag', function (t) {
+  documentation(['build fixture/infer-private.input.js --infer-private ^_'], {}, function (err, data) {
+    t.error(err);
+
+    // This uses JSON.parse with a reviver used as a visitor.
+    JSON.parse(data, function (n, v) {
+      // Make sure we do not see any names that match `^_`.
+      if (n === 'name') {
+        t.equal(typeof v, 'string');
+        t.ok(!/_$/.test(v));
+      }
+      return v;
+    });
+    t.end();
+  }, false);
+});
+
 test('write to file', function (t) {
 
   var dst = path.join(os.tmpdir(), (Date.now() + Math.random()).toString());

test/fixture/infer-private.input.js

@@ -0,0 +1,12 @@
+/**
+ * _p description
+ */
+function _p() {}
+
+/** C description */
+class C {
+  /** m description */
+  m() {}
+  /** _p description */
+  _p() {}
+}