Unkink option parsing options

Author: tmcw

bin/documentation.js

@@ -13,57 +13,15 @@ var parsedArgs = parseArgs();
 commands[parsedArgs.command](documentation, parsedArgs);
 
 function parseArgs() {
-  // reset() needs to be called at parse time because the yargs module uses an
-  // internal global variable to hold option state
-  var argv = addCommands(yargs, true)
-    .usage('Usage: $0 <command> [options]')
+
+  var commandArgv = addCommands(yargs)
     .version(function () {
       return require('../package').version;
     })
-    .option('shallow', {
-      describe: 'shallow mode turns off dependency resolution, ' +
-      'only processing the specified files (or the main script specified in package.json)',
-      default: false,
-      type: 'boolean'
-    })
-    .option('config', {
-      describe: 'configuration file. an array defining explicit sort order',
-      alias: 'c'
-    })
-    .option('external', {
-      describe: 'a string / glob match pattern that defines which external ' +
-        'modules will be whitelisted and included in the generated documentation.',
-      default: null
-    })
-    .option('extension', {
-      describe: 'only input source files matching this extension will be parsed, ' +
-        'this option can be used multiple times.',
-      alias: 'e'
-    })
-    .option('polyglot', {
-      type: 'boolean',
-      describe: 'polyglot mode turns off dependency resolution and ' +
-        'enables multi-language support. use this to document c++'
-    })
-    .option('private', {
-      describe: 'generate documentation tagged as private',
-      type: 'boolean',
-      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',
-      alias: 'g'
-    })
-  .argv;
+    .argv;
+
+  var argv = commands[commandArgv._[0]]
+    .parseArgs(yargs.reset()).argv;
 
   var options = {};
   if (argv.config) {
@@ -109,14 +67,8 @@ function parseArgs() {
 }
 
 function addCommands(parser, descriptionOnly) {
-  parser = parser.demand(1);
-  for (var cmd in commands) {
-    if (descriptionOnly) {
-      parser = parser.command(cmd, commands[cmd].description);
-    } else {
-      parser = parser.command(cmd, commands[cmd].description, commands[cmd].parseArgs);
-    }
-  }
-  return parser.help('help');
+  return Object.keys(commands).reduce(function(parser, cmd) {
+    return parser.command(cmd, commands[cmd].description);
+  }, parser.demand(1)).help('help');
 }
 

lib/commands/build.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var streamArray = require('stream-array'),
+  sharedOptions = require('./shared_options'),
   fs = require('fs'),
   vfs = require('vinyl-fs'),
   chokidar = require('chokidar'),
@@ -10,26 +11,21 @@ module.exports = build;
 module.exports.description = 'build documentation';
 
 module.exports.parseArgs = function (yargs) {
-  var argv = addOutputArgs(yargs)
-  .option('format', {
-    alias: 'f',
-    default: 'json',
-    choices: ['json', 'md', 'html']
-  })
-  .option('output', {
-    describe: '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',
-    alias: 'o'
-  })
-  .example('$0 build foo.js -f md > API.md', 'parse documentation in a ' +
-    'file and generate API documentation as Markdown')
-  .argv;
-
-  if (argv.f === 'html' && argv.o === 'stdout') {
-    yargs.showHelp();
-    throw new Error('The HTML output mode requires a destination directory set with -o');
-  }
+  return sharedOptions.sharedOutputOptions(
+    sharedOptions.sharedInputOptions(yargs))
+    .option('format', {
+      alias: 'f',
+      default: 'json',
+      choices: ['json', 'md', 'html']
+    })
+    .option('output', {
+      describe: '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',
+      alias: 'o'
+    })
+    .example('$0 build foo.js -f md > API.md', 'parse documentation in a ' +
+      'file and generate API documentation as Markdown');
 };
 
 /*
@@ -96,24 +92,3 @@ function build(documentation, parsedArgs, callback) {
     }));
   }
 }
-
-// export this so `serve` can use it also
-module.exports.addOutputArgs = addOutputArgs;
-function addOutputArgs(yargs) {
-  return yargs.option('theme', {
-    describe: 'specify a theme: this must be a valid theme module',
-    alias: 't'
-  })
-  .option('name', {
-    describe: 'project name. by default, inferred from package.json'
-  })
-  .option('watch', {
-    describe: 'watch input files and rebuild documentation when they change',
-    alias: 'w',
-    type: 'boolean'
-  })
-  .option('project-version', {
-    describe: 'project version. by default, inferred from package.json'
-  })
-  .help('help');
-}

lib/commands/lint.js

@@ -5,8 +5,9 @@
 module.exports = lint;
 module.exports.description = 'check for common style and uniformity mistakes';
 module.exports.parseArgs = function (yargs) {
-  yargs.example('$0 lint project.js', 'check documentation style')
-  .help('help');
+  return yargs
+    .example('$0 lint project.js', 'check documentation style')
+    .help('help');
 };
 
 function lint(documentation, parsedArgs) {

lib/commands/readme.js

@@ -10,7 +10,7 @@ var build = require('./build');
 module.exports = readme;
 module.exports.description = 'inject documentation into your README.md';
 module.exports.parseArgs = function (yargs) {
-  yargs.usage('Usage: $0 readme [--readme-file=README.md] --section "API"' +
+  return yargs.usage('Usage: $0 readme [--readme-file=README.md] --section "API"' +
     ' [--compare-only] [other documentationjs options]')
   .option('readme-file', {
     describe: 'The markdown file into which to inject documentation',

lib/commands/serve.js

@@ -1,13 +1,17 @@
 'use strict';
 
 var errorPage = require('../../lib/error_page'),
+  sharedOptions = require('./shared_options'),
   Server = require('../../lib/server');
 
 var build = require('./build');
 
 module.exports = serve;
 module.exports.description = 'generate, update, and display HTML documentation';
-module.exports.parseArgs = build.addOutputArgs;
+module.exports.parseArgs = function (yargs) {
+  return sharedOptions.sharedOutputOptions(
+      sharedOptions.sharedInputOptions(yargs));
+};
 
 var server = new Server();
 server.on('listening', function () {

lib/commands/shared_options.js

@@ -0,0 +1,70 @@
+/**
+ * Adds shared options to any command that runs documentation
+ */
+function sharedInputOptions(parser) {
+  return parser.option('shallow', {
+    describe: 'shallow mode turns off dependency resolution, ' +
+    'only processing the specified files (or the main script specified in package.json)',
+    default: false,
+    type: 'boolean'
+  })
+  .option('config', {
+    describe: 'configuration file. an array defining explicit sort order',
+    alias: 'c'
+  })
+  .option('external', {
+    describe: 'a string / glob match pattern that defines which external ' +
+      'modules will be whitelisted and included in the generated documentation.',
+    default: null
+  })
+  .option('extension', {
+    describe: 'only input source files matching this extension will be parsed, ' +
+      'this option can be used multiple times.',
+    alias: 'e'
+  })
+  .option('polyglot', {
+    type: 'boolean',
+    describe: 'polyglot mode turns off dependency resolution and ' +
+      'enables multi-language support. use this to document c++'
+  })
+  .option('private', {
+    describe: 'generate documentation tagged as private',
+    type: 'boolean',
+    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',
+    alias: 'g'
+  });
+};
+
+function sharedOutputOptions(yargs) {
+  return yargs.option('theme', {
+    describe: 'specify a theme: this must be a valid theme module',
+    alias: 't'
+  })
+  .option('name', {
+    describe: 'project name. by default, inferred from package.json'
+  })
+  .option('watch', {
+    describe: 'watch input files and rebuild documentation when they change',
+    alias: 'w',
+    type: 'boolean'
+  })
+  .option('project-version', {
+    describe: 'project version. by default, inferred from package.json'
+  })
+  .help('help');
+}
+
+module.exports.sharedOutputOptions = sharedOutputOptions;
+module.exports.sharedInputOptions = sharedInputOptions;