documentationjs · arv · May 25, 2016 · Aug 18, 2016 · Aug 22, 2016
diff --git a/docs/USAGE.md b/docs/USAGE.md
@@ -19,37 +19,41 @@ 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]
-  --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"]
+  --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]
+  --document-exported  Generate documentation for all exported bindings and
+                       members even if there is no JSDoc for them
+                                                      [boolean] [default: false]
+  --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", "remark", "html"] [default: "json"]
 
 Examples:
   documentation build foo.js -f md >        parse documentation in a file and

diff --git a/index.js b/index.js
@@ -194,7 +194,7 @@ function buildSync(indexes, options) {
             return [];
           }
 
-          return parseFn(indexObject).map(buildPipeline);
+          return parseFn(indexObject, options).map(buildPipeline);
         })
         .filter(Boolean), options)));
 }
@@ -249,7 +249,7 @@ function lint(indexes, options, callback) {
         inputs
           .filter(filterJS(options.extension, options.polyglot))
           .reduce(function (memo, file) {
-            return memo.concat(parseFn(file).map(lintPipeline));
+            return memo.concat(parseFn(file, options).map(lintPipeline));
           }, [])
           .filter(Boolean))));
   });

diff --git a/lib/commands/shared_options.js b/lib/commands/shared_options.js
@@ -53,6 +53,12 @@ function sharedInputOptions(parser) {
     type: 'string',
     describe: 'Infer private access based on the name. This is a regular expression that ' +
       'is used to match the name'
+  })
+  .option('document-exported', {
+    type: 'boolean',
+    describe: 'Generate documentation for all exported bindings and members ' +
+      'even if there is no JSDoc for them',
+    default: false
   });
 }
 

diff --git a/lib/parsers/javascript.js b/lib/parsers/javascript.js
@@ -27,9 +27,11 @@ function leftPad(str, width) {
  * reads the file, parses the JavaScript, and parses the JSDoc.
  *
  * @param {Object} data a chunk of data provided by module-deps
+ * @param {Object} options options
  * @return {Array<Object>} an array of parsed comments
  */
-function parseJavaScript(data) {
+function parseJavaScript(data, options) {
+  options = options || {};
   var results = [];
   var ast = babylon.parse(data.source, {
     allowImportExportEverywhere: true,
@@ -80,31 +82,7 @@ function parseJavaScript(data) {
          * @return {undefined} this emits data
          */
         function parseComment(comment) {
-          var context = {
-            loc: extend({}, JSON.parse(JSON.stringify(path.node.loc))),
-            file: data.file,
-            sortKey: data.sortKey + ' ' + leftPad(path.node.loc.start.line, 8)
-          };
-          // Avoid visiting the same comment twice as a leading
-          // and trailing node
-          var key = JSON.stringify(comment.loc);
-          if (!visited[key]) {
-            visited[key] = true;
-            if (includeContext) {
-              // This is non-enumerable so that it doesn't get stringified in
-              // output; e.g. by the documentation binary.
-              Object.defineProperty(context, 'ast', {
-                enumerable: false,
-                value: path
-              });
-
-              if (path.parentPath && path.parentPath.node) {
-                context.code = data.source.substring
-                  .apply(data.source, path.parentPath.node.range);
-              }
-            }
-            results.push(parse(comment.value, comment.loc, context));
-          }
+          addComment(comment.value, comment.loc, path, path.node.loc, includeContext);
         }
 
         (path.node[type] || [])
@@ -116,10 +94,86 @@ function parseJavaScript(data) {
     traverse.clearCache();
   }
 
+  function addComment(commentValue, commentLoc, path, nodeLoc, includeContext) {
+    var context = {
+      loc: extend({}, JSON.parse(JSON.stringify(nodeLoc))),
+      file: data.file,
+      sortKey: data.sortKey + ' ' + leftPad(nodeLoc.start.line, 8)
+    };
+    // Avoid visiting the same comment twice as a leading
+    // and trailing node
+    var key = JSON.stringify(commentLoc);
+    if (!visited[key]) {
+      visited[key] = true;
+      if (includeContext) {
+        // This is non-enumerable so that it doesn't get stringified in
+        // output; e.g. by the documentation binary.
+        Object.defineProperty(context, 'ast', {
+          enumerable: false,
+          value: path
+        });
+
+        if (path.parentPath && path.parentPath.node) {
+          context.code = data.source.substring
+            .apply(data.source, path.parentPath.node.range);
+        }
+      }
+      results.push(parse(commentValue, commentLoc, context));
+    }
+  }
+
+  function addBlankComment(path, node) {
+    addComment('', node.loc, path, node.loc, true);
+  }
+
+  function walkExported(ast) {
+    traverse(ast, {
+      enter: function (path) {
+        if (path.isExportDeclaration()) {
+          if (!hasJSDocComment(path)) {
+            if (!path.node.declaration) {
+              return;
+            }
+            const node = path.node.declaration;
+            addBlankComment(path, node);
+          }
+        } else if ((path.isClassProperty() || path.isClassMethod()) &&
+            !hasJSDocComment(path) && inExportedClass(path)) {
+          addBlankComment(path, path.node);
+        } else if ((path.isObjectProperty() || path.isObjectMethod()) &&
+            !hasJSDocComment(path) && inExportedObject(path)) {
+          addBlankComment(path, path.node);
+        }
+      }
+    });
+  }
+
+  function hasJSDocComment(path) {
+    return path.node.leadingComments && path.node.leadingComments.some(isJSDocComment);
+  }
+
+  function inExportedClass(path) {
+    var c = path.parentPath.parentPath;
+    return c.isClass() && c.parentPath.isExportDeclaration();
+  }
+
+  function inExportedObject(path) {
+    // ObjectExpression -> VariableDeclarator -> VariableDeclaration -> ExportNamedDeclaration
+    var p = path.parentPath.parentPath;
+    if (!p.isVariableDeclarator()) {
+      return false;
+    }
+    return p.parentPath.parentPath.isExportDeclaration();
+  }
+
   walkComments(ast, 'leadingComments', true);
   walkComments(ast, 'innerComments', false);
   walkComments(ast, 'trailingComments', false);
 
+  if (options.documentExported) {
+    walkExported(ast);
+  }
+
   return results;
 }
 

diff --git a/test/bin.js b/test/bin.js
@@ -341,3 +341,19 @@ test('fatal error', options, function (t) {
       t.end();
     }, false);
 });
+
+test('build --document-exported', function (t) {
+
+  documentation(['build fixture/document-exported.input.js --document-exported -f md'], {}, function (err, data) {
+    t.error(err);
+
+    var outputfile = path.join(__dirname, 'fixture', 'document-exported.output.md');
+    if (process.env.UPDATE) {
+      fs.writeFileSync(outputfile, data, 'utf8');
+    }
+
+    var expect = fs.readFileSync(outputfile, 'utf-8');
+    t.equal(data, expect);
+    t.end();
+  }, false);
+}, options);
diff --git a/test/fixture/document-exported.input.js b/test/fixture/document-exported.input.js
@@ -0,0 +1,35 @@
+// Options: {"documentExported": true}
+
+export class Class {
+  classMethod() {}
+  get classGetter() {}
+  set classSetter(v) {}
+  static staticMethod() {}
+  static get staticGetter() {}
+  static set staticSetter(v) {}
+}
+
+export var object =  {
+  method() {},
+  get getter() {},
+  set setter(v) {},
+  prop: 42,
+  func: function() {},
+};
+
+class NotExportedClass {
+  classMethod() {}
+  get classGetter() {}
+  set classSetter(v) {}
+  static staticMethod() {}
+  static get staticGetter() {}
+  static set staticSetter(v) {}
+}
+
+var notExportedObject =  {
+  method() {},
+  get getter() {},
+  set setter(v) {},
+  prop: 42,
+  func: function() {},
+};