Improve binary by providing command-specific help strings

Author: tmcw

lib/args.js

@@ -2,36 +2,27 @@ var path = require('path'),
   yargs = require('yargs'),
   loadConfig = require('../lib/load_config.js');
 
-function parse(args) {
-  // reset() needs to be called at parse time because the yargs module uses an
-  // internal global variable to hold option state
-  return yargs.reset()
-  .usage('Usage: $0 <command> [options]')
-
-  .demand(1)
-
-  .command('build', 'build documentation')
-  .command('lint', 'check for common style and uniformity mistakes')
-  .command('serve', 'generate, update, and display HTML documentation')
-
-  .version(function () {
-    return require('../package').version;
+function commonOptions(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'
   })
-
-  .help('help')
-  .alias('help', 'h')
-
-  .option('format', {
-    alias: 'f',
-    default: 'json',
-    choices: ['json', 'md', 'html']
+  .option('config', {
+    describe: 'configuration file. an array defining explicit sort order',
+    alias: 'c'
   })
-  .option('watch', {
-    describe: 'watch input files and rebuild documentation when they change',
-    alias: 'w',
-    type: 'boolean'
+  .option('polyglot', {
+    type: 'boolean',
+    describe: 'polyglot mode turns off dependency resolution and ' +
+      'enables multi-language support. use this to document c++'
   })
-  .option('theme', {
+  .help('help');
+}
+
+function outputOptions(parser) {
+  return parser.option('theme', {
     describe: 'specify a theme: this must be a valid theme module',
     alias: 't'
   })
@@ -44,42 +35,65 @@ function parse(args) {
   .option('name', {
     describe: 'project name. by default, inferred from package.json'
   })
-  .option('project-version', {
-    describe: 'project version. by default, inferred from package.json'
-  })
-  .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('polyglot', {
-    type: 'boolean',
-    describe: 'polyglot mode turns off dependency resolution and ' +
-      'enables multi-language support. use this to document c++'
-  })
   .option('github', {
     type: 'boolean',
     describe: 'infer links to github in documentation',
     alias: 'g'
   })
-  .option('config', {
-    describe: 'configuration file. an array defining explicit sort order',
-    alias: 'c'
-  })
-  .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'
+  .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'
+  });
+}
 
-  .example('$0 build foo.js -f md > API.md', 'parse documentation in a ' +
-    'file and generate API documentation as Markdown')
+function parse(args) {
+  // reset() needs to be called at parse time because the yargs module uses an
+  // internal global variable to hold option state
+  var command = yargs.reset()
+    .usage('Usage: $0 <command> [options]')
+    .demand(1)
+    .command('build', 'build documentation')
+    .command('lint', 'check for common style and uniformity mistakes')
+    .command('serve', 'generate, update, and display HTML documentation')
+    .version(function () {
+      return require('../package').version;
+    })
+    .parse(args)._[0];
+
+  if (command === 'build') {
+    return outputOptions(commonOptions(yargs.reset()))
+      .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')
+      .parse(args);
+  }
 
-  .example('$0 lint project.js', 'check documentation style')
+  if (command === 'serve') {
+    return outputOptions(commonOptions(yargs.reset())).parse(args);
+  }
+
+  if (command === 'lint') {
+    return commonOptions(yargs.reset())
+      .example('$0 lint project.js', 'check documentation style')
+      .parse(args);
+  }
 
-  .parse(args)
+  yargs.showHelp();
+  process.exit(1);
 }
 
 /**
@@ -89,12 +103,10 @@ function parse(args) {
  * @private
  */
 module.exports = function (args) {
-  var argv = parse(args);
-
-  var command = argv._[0],
-    inputs = argv._.slice(1);
-
-  var name = argv.name,
+  var argv = parse(args),
+    command = argv._[0],
+    inputs = argv._.slice(1),
+    name = argv.name,
     version = argv['project-version'],
     transform;
 
@@ -149,5 +161,3 @@ module.exports = function (args) {
     output: argv.o
   }
 }
-
-

test/bin.js

@@ -156,6 +156,13 @@ test('given no files', function (t) {
   });
 }, options);
 
+test('with an invalid command', function (t) {
+  documentation(['invalid'], function (err) {
+    t.ok(err, 'returns error');
+    t.end();
+  });
+}, options);
+
 test('write to file', function (t) {
 
   var dst = path.join(os.tmpdir(), (Date.now() + Math.random()).toString());