Fix args regression: readme --shallow --format (Invalid second argument) (#968)

* Add shared_options to readme command.

This makes --shallow and --format work again.

* Update yarn.lock based on package.json.

* Move readme example to where it works,

remove superfluous usage string.

yargs@>=7 throws exceptions on incorrectly structured builder objects.

* Update expected readme test fixture.

* Update bin-readme snapshot.

* s/_.assign/Object.assign/g thanks to node@>=4.

* Update yarn.lock based on package.json (lint-staged@6)

* Override flow error message.

Author: hugojosefson

__tests__/__snapshots__/bin-readme.js.snap

@@ -7,6 +7,11 @@ exports[`readme command --readme-file 1`] = `
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [foo](#foo)
+-   [bar](#bar)
+
 ## foo
 
 A function with documentation.
@@ -36,6 +41,11 @@ exports[`readme command updates README.md 1`] = `
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [foo](#foo)
+-   [bar](#bar)
+
 ## foo
 
 A function with documentation.

__tests__/fixture/readme/README.output.md

@@ -4,6 +4,11 @@
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [foo](#foo)
+-   [bar](#bar)
+
 ## foo
 
 A function with documentation.

bin/documentation.js

@@ -21,6 +21,7 @@ var argv = yargs
     }
   })
   .example('documentation build foo.js -f md > API.md')
+  .example('documentation readme index.js -s "API Docs" --github')
   .version()
   .usage(
     `Usage:

src/commands/build.js

@@ -18,7 +18,7 @@ module.exports.describe = 'build documentation';
  * @returns {Object} yargs with options
  * @private
  */
-module.exports.builder = _.assign(
+module.exports.builder = Object.assign(
   {},
   sharedOptions.sharedOutputOptions,
   sharedOptions.sharedInputOptions,

src/commands/readme.js

@@ -4,46 +4,49 @@ var fs = require('fs');
 var remark = require('remark');
 var path = require('path');
 var documentation = require('../');
+var sharedOptions = require('./shared_options');
 var inject = require('mdast-util-inject');
 var chalk = require('chalk');
 var disparity = require('disparity');
 
 module.exports.command = 'readme [input..]';
 module.exports.description = 'inject documentation into your README.md';
+
 /**
  * Add yargs parsing for the readme command
  * @param {Object} yargs module instance
  * @returns {Object} yargs with options
  * @private
  */
-module.exports.builder = {
-  usage:
-    'Usage: documentation readme [--readme-file=README.md] --section "API"' +
-    ' [--compare-only] [other documentationjs options]',
-  example: 'documentation readme index.js -s "API Docs" --github',
-  'readme-file': {
-    describe: 'The markdown file into which to inject documentation',
-    default: 'README.md'
-  },
-  section: {
-    alias: 's',
-    describe:
-      'The section heading after which to inject generated documentation',
-    required: true
-  },
-  'diff-only': {
-    alias: 'd',
-    describe:
-      'Instead of updating the given README with the generated documentation,' +
-      ' just check if its contents match, exiting nonzero if not.',
-    default: false
-  },
-  quiet: {
-    alias: 'q',
-    describe: 'Quiet mode: do not print messages or README diff to stdout.',
-    default: false
+module.exports.builder = Object.assign(
+  {},
+  sharedOptions.sharedOutputOptions,
+  sharedOptions.sharedInputOptions,
+  {
+    'readme-file': {
+      describe: 'The markdown file into which to inject documentation',
+      default: 'README.md'
+    },
+    section: {
+      alias: 's',
+      describe:
+        'The section heading after which to inject generated documentation',
+      required: true
+    },
+    'diff-only': {
+      alias: 'd',
+      describe:
+        'Instead of updating the given README with the generated documentation,' +
+        ' just check if its contents match, exiting nonzero if not.',
+      default: false
+    },
+    quiet: {
+      alias: 'q',
+      describe: 'Quiet mode: do not print messages or README diff to stdout.',
+      default: false
+    }
   }
-};
+);
 
 /**
  * Insert API documentation into a Markdown readme

src/commands/serve.js

@@ -18,7 +18,7 @@ module.exports.description = 'generate, update, and display HTML documentation';
  * @returns {Object} yargs with options
  * @private
  */
-module.exports.builder = _.assign(
+module.exports.builder = Object.assign(
   {},
   sharedOptions.sharedOutputOptions,
   sharedOptions.sharedInputOptions,

src/infer/params.js

@@ -55,7 +55,7 @@ function inferAndCombineParams(params, comment) {
   var mergedParamsAndErrors = mergeTrees(inferredParams, comment.params);
 
   // Then merge the trees. This is the hard part.
-  return _.assign(comment, {
+  return Object.assign(comment, {
     params: mergedParamsAndErrors.mergedParams,
     errors: comment.errors.concat(mergedParamsAndErrors.errors)
   });
@@ -114,7 +114,7 @@ function paramToDoc(
         throw new Error('Encountered an unexpected parameter type');
       }
 
-      return _.assign(newAssignmentParam, {
+      return Object.assign(newAssignmentParam, {
         default: generate(param.right, {
           compact: true
         }).code,
@@ -181,7 +181,7 @@ function paramToDoc(
           // instead we're going to (immutably) rename the parameters to their
           // indices
           properties: _.flatMap(param.elements, (element, idx) => {
-            var indexedElement = _.assign({}, element, {
+            var indexedElement = Object.assign({}, element, {
               name: String(idx),
               indexed: true
             });
@@ -190,16 +190,22 @@ function paramToDoc(
         };
       }
       return _.flatMap(param.elements, (element, idx) => {
-        var indexedElement = _.assign({}, element, {
+        var indexedElement = Object.assign({}, element, {
           name: String(idx)
         });
         return paramToDoc(indexedElement, prefix);
       });
     }
     case 'ObjectProperty': {
-      return _.assign(paramToDoc(param.value, prefix + '.' + param.key.name || param.key.value), {
-        name: prefix + '.' + param.key.name || param.key.value
-      });
+      return Object.assign(
+        ((paramToDoc(
+          param.value,
+          prefix + '.' + param.key.name || param.key.value
+        ): any): CommentTag),
+        {
+          name: prefix + '.' + param.key.name || param.key.value
+        }
+      );
     }
     case 'RestProperty': // (a, ...b)
     case 'RestElement': {
@@ -342,7 +348,7 @@ function combineTags(inferredTag, explicitTag) {
     (inferredTag.properties && inferredTag.properties.length) ||
     (explicitTag.properties && explicitTag.properties.length);
 
-  return _.assign(
+  return Object.assign(
     explicitTag,
     hasProperties
       ? {

src/nest.js

@@ -46,7 +46,7 @@ var nestTag = (
         // get to this case because the recursive method
         // is always passed parts.slice(1)
         if (parts.length === 1) {
-          _.assign(node, {
+          Object.assign(node, {
             properties: (node.properties || []).concat(tag)
           });
         } else {
@@ -62,7 +62,9 @@ var nestTag = (
             if (tag.name.match(/^(\$\d+)/)) {
               errors.push({
                 message:
-                  `Parent of ${tag.name} not found. To document a destructuring\n` +
+                  `Parent of ${
+                    tag.name
+                  } not found. To document a destructuring\n` +
                   `type, add a @param tag in its position to specify the name of the\n` +
                   `destructured parameter`,
                 commentLineNumber: tag.lineNumber