edit docs, cleanup cli.processGrammars

options argument properties are documented better. Optional and default
args specified better. jsonMode arg to cli.processGrammars means
something.

lib/cli.js

@@ -18,28 +18,28 @@
 var cli = exports;
 /**
  * Generates a parser and writes it to a file.
- * @param {Object} opts Options object.
- * 
- * Options: <br><br>
- * file: {String} Optional. Path to a file containing a grammar. If no file is
- *  specified input will be read from stdin. <br><br>
- *
- * lexfile: {String} Optional. Path to a file containing a lexical grammar. <br><br>
- *
- * json: {Boolean} Optional. Set to true if `file` is in json format. <br><br>
- *
- * outfile: {String} Optional. The path and filename where the parser should be
- *  written to. Defaults to the path and filename given for `file` with the file
- *  extension replaced by `js`. <br><br>
- *
- * debug: {Boolean} Optional. Debug mode. Defaults to false. <br><br>
- *
- * module-type: {String} Optional. The module type of the generated parser.
- *  Options are: commonjs, amd, and js. Defaults to commonjs. <br><br>
- *
- * parser-type: {String} Optional. The type of parser to generate. Options are:
- *  lr0, slr, lalr, and lr. Defaults to lalr. <br><br>
- *
+ * @param {Object} [opts = {}]
+ *  Options object.
+ * @param {String} [opts.file = null]
+ *  Path to a file containing a grammar. If no file is specified input will be
+ *  read from stdin.
+ * @param {String} [opts.lexfile = null]
+ *  Path to a file containing a lexical grammar.
+ * @param {String} [opts.outfile = opts.file.replace(/\.[^.]*$/, ".js")]
+ *  The path and filename where the parser should be written to. Defaults to the
+ *  path and filename given for <code>file</code> with the file extension
+ *  replaced by <code>js</code>.
+ * @param {Boolean} [opts.json = false]
+ *  Set to true if `file` is in json format.
+ * @param {String} [opts.moduleName = "parser"]
+ *  The internal name for your module in the generated parser.
+ * @param {Boolean} [opts.debug = false] Debug mode.
+ * @param {String} [opts['module-type'] = "commonjs"]
+ *  The module type of the generated parser. Options are: <code>commonjs</code>,
+ *  <code>amd</code>, <code>and</code> <code>js</code>.
+ * @param {String} [opts['parser-type'] = "lalr"]
+ *  The type of parser to generate. Options are: <code>lr0</code>,
+ *  <code>slr</code>, <code>lalr</code>, and <code>lr</code>.
  * @example
  *  // grammar to process is not json and contains grammars for lexer and
  *  // parser.
@@ -77,6 +77,11 @@ cli.main = function cli_main(opts) {
     opts = opts || {};
     /**
      * Generates a parser as a string.
+     * @param {String} raw Contents of the file named in <code>opts.file</code>
+     *  argument of {@link cli.main}
+     * @param {String} lex Contents of the file named in <code>opts.lexfile</code>
+     *  argument of {@link cli.main}
+     * @param {Object} Options object supplied to {@link cli.main}
      * @private
      */
     function processGrammar(raw, lex, opts) {
@@ -162,9 +167,18 @@ cli.main = function cli_main(opts) {
 };
 /**
  * Generates a parser and returns it as a string.
- * @param {Object} opts Optional. An options object. Options are parser-type,
- *  module-type, and debug. Defaults to {}; see the description and examples for
- *  these optons in {@link cli.main}
+ * @param {Object} [opts = {}]
+ *  An options object.
+ * @param {Boolean} [opts.json]
+ *  See the description in {@link cli.main}
+ * @param {String} [opts.moduleName]
+ *  See the description in {@link cli.main}
+ * @param {Object} [opts.debug]
+ *  See the description in {@link cli.main}
+ * @param {Object} [opts['parser-type']]
+ *  See the description in {@link cli.main}
+ * @param {Object} [opts['module-type']]
+ *  See the description in {@link cli.main}
  * @param {String|Object} grammar The grammar to generate a parser from.
  * @returns {String} Returns the generated parser as a string.
  * @requires <a href="https://npmjs.org/package/jison/">jison</a>
@@ -190,36 +204,36 @@ cli.generateParserString = function generateParserString(opts, grammar) {
 /**
  * Processes grammar files of various format.
  * @param {String} file Contents of a jison grammar file.
- * @param {String} lexFile Contents of a lexer grammar file.
- * @param {Boolean} jsonMode Set to true if `file` is in json format.
+ * @param {String} [lexFile] Contents of a lexer grammar file.
+ * @param {Boolean} [jsonMode = false] Set to true if <code>file</code> is in
+ *  json format.
  * @returns {Object} Returns the parsed grammar object.
  * @requires <a href="https://npmjs.org/package/ebnf-parser">ebnf-parser</a>
  * @requires <a href="https://npmjs.org/package/cjson">cjson</a>
  * @requires <a href="https://npmjs.org/package/lex-parser">lex-parser</a>
  */
 cli.processGrammars = function processGrammars(file, lexFile, jsonMode) {
     "use strict";
+    lexFile = lexFile || false;
+    jsonMode = jsonMode || false;
     var ebnfParser = require('ebnf-parser');
     var cjson = require('cjson');
-
     var grammar;
-    if (jsonMode) {
-        grammar = cjson.parse(file);
-    } else {
-        // otherwise, attempt to parse jison format
-        // fallback to JSON
-        try {
+    try {
+        if (jsonMode) {
+            grammar = cjson.parse(file);
+        } else {
             grammar = ebnfParser.parse(file);
-        } catch (e) {
-            try {
-                grammar = cjson.parse(file);
-            } catch (e2) {
-                throw e;
-            }
         }
+    } catch (e) {
+        throw new Error('Could not parse jison grammar');
     }
-    if (lexFile) {
-        grammar.lex = require('lex-parser').parse(lexFile);
+    try {
+        if (lexFile) {
+            grammar.lex = require('lex-parser').parse(lexFile);
+        }
+    } catch (e) {
+        throw new Error('Could not parse lex grammar');
     }
     return grammar;
 };