Parse options and add docs

package.json

@@ -21,6 +21,7 @@
     "jshint": "~2.4.4",
     "jsdoc": "~3.3.0-alpha5",
     "walk": "~2.3.1",
-    "fs-extra": "~0.8.1"
+    "fs-extra": "~0.8.1",
+    "nomnom": "~1.6.2"
   }
 }

tasks/build.js

@@ -7,6 +7,7 @@ var path = require('path');
 var async = require('async');
 var closure = require('closure-util');
 var fse = require('fs-extra');
+var nomnom = require('nomnom');
 
 var generateExports = require('./generate-exports');
 
@@ -66,7 +67,7 @@ function readConfig(configPath, callback) {
  *     or any error.
  */
 function getDependencies(callback) {
-  log.info('ol', 'Parsing dependencies ...');
+  log.info('ol', 'Parsing dependencies');
   closure.getDependencies({lib: ['src/**/*.js']}, function(err, paths) {
     if (err) {
       callback(err);
@@ -86,7 +87,7 @@ function getDependencies(callback) {
  *     any error.
  */
 function build(options, paths, callback) {
-  log.info('ol', 'Compiling ...');
+  log.info('ol', 'Compiling ' + paths.length + ' sources');
   options.js = paths;
   closure.compile(options, callback);
 }
@@ -114,12 +115,37 @@ function main(config, callback) {
  * function.
  */
 if (require.main === module) {
-  var configPath = process.argv[2];
+  var options = nomnom.options({
-  var outputPath = process.argv[3];
+    config: {
+      position: 0,
+      required: true,
+      help: 'Path to JSON config file'
+    },
+    output: {
+      position: 1,
+      required: true,
+      help: 'Output file path'
+    },
+    loglevel: {
+      abbr: 'l',
+      choices: ['silly', 'verbose', 'info', 'warn', 'error'],
+      default: 'info',
+      help: 'Log level',
+      metavar: 'LEVEL'
+    }
+  }).parse();
+
+  /**
+   * Set the log level.
+   * @type {string}
+   */
+  log.level = options.loglevel;
+
+  // read the config, run the main function, and write the output file
   async.waterfall([
-    readConfig.bind(null, configPath),
+    readConfig.bind(null, options.config),
     main,
-    fse.outputFile.bind(fse, outputPath)
+    fse.outputFile.bind(fse, options.output)
   ], function(err) {
     if (err) {
       log.error(err.message);

tasks/readme.md

@@ -0,0 +1,67 @@
+# Tasks
+
+This directory contains utility scripts for working with the library.
+
+
+## `build.js`
+
+Builds the library based on a configuration file.  See the `--help` option for more detail.
+
+    node tasks/build.js --help
+
+### Build configuration files
+
+Build configuration files are JSON files that are used to determine what should be exported from the library and what options should be passed to the compiler.
+
+ * **exports** - `Array.<string>` An array of symbol names or patterns to be exported (names that are used in your application).  For example, including `"ol.Map"` will export the map constructor.  Method names are prefixed with `#`.  So `"ol.Map#getView"` will export the map's `getView` method.  You can use a `*` at the end to match multiple names.  The pattern `"ol.Map#*"` will export all map methods.
+
+ * **compile** - `Object` An object whose properties are [Closure Compiler options](https://github.com/openlayers/closure-util/blob/master/compiler-options.txt).  Property names match the option names without the `--` prefix (e.g. `"compilation_level": "ADVANCED_OPTIMIZATIONS"` would set the `--compilation_level` option).  Where an option can be specified multiple times, use an array for the value (e.g. `"externs": ["one.js", "two.js"]`).  Where an option is used as a flag, use a boolean value (e.g. `"use_types_for_optimization": true`).
+
+Below is a complete `build.json` configuration file that would generate a build including every symbol in the library (much more than you'd ever need).
+
+```json
+{
+  "exports": ["*"],
+  "compile": {
+    "compilation_level": "ADVANCED_OPTIMIZATIONS",
+    "use_types_for_optimization": true,
+    "externs": [
+      "externs/olx.js",
+      "externs/oli.js",
+      "externs/geojson.js"
+    ],
+    "define": [
+      "ol.ENABLE_PROJ4JS=false",
+      "goog.dom.ASSUME_STANDARDS_MODE=true",
+      "goog.DEBUG=false"
+    ],
+    "output_wrapper": "(function(){%output%})();"
+  }
+}
+```
+
+To generate a build named `ol.min.js` with the `build.json`, you would run this:
+
+    node tasks/build.js build.json ol.min.js
+
+
+## `generate-exports.js`
+
+Called internally to generate a `build/exports.js` file optionally with a limited set of exports.
+
+
+## `generate-symbols.js`
+
+Called internally to parse the library for API annotations and write out a `build/symbols.json` file.
+
+
+## `parse-examples.js`
+
+Called after install to generate an example index.  After new examples are added, run `node tasks/parse-examples.js` to regenerate the example index.
+
+
+## `serve.js`
+
+Run a debug server that provides all library sources unminified.  Provides a static server for examples and tests.  See the `--help` option for more detail.
+
+    node tasks/serve.js --help

tasks/serve.js

@@ -8,8 +8,30 @@ var path = require('path');
 var url = require('url');
 
 var closure = require('closure-util');
+var nomnom = require('nomnom');
+
 var log = closure.log;
 
+var options = nomnom.options({
+  port: {
+    abbr: 'p',
+    default: 3000,
+    help: 'Port for incoming connections',
+    metavar: 'PORT'
+  },
+  loglevel: {
+    abbr: 'l',
+    choices: ['silly', 'verbose', 'info', 'warn', 'error'],
+    default: 'info',
+    help: 'Log level',
+    metavar: 'LEVEL'
+  }
+}).parse();
+
+
+/** @type {string} */
+log.level = options.loglevel;
+
 log.info('ol', 'Parsing dependencies ...');
 var manager = new closure.Manager({
   closure: true, // use the bundled Closure Library
@@ -40,8 +62,9 @@ manager.on('ready', function() {
       return main;
     }
   });
-  server.listen(3000, function() {
+  server.listen(options.port, function() {
-    log.info('ol', 'Listening on http://localhost:3000/ (Ctrl+C to stop)');
+    log.info('ol', 'Listening on http://localhost:' +
+        options.port + '/ (Ctrl+C to stop)');
   });
   server.on('error', function(err) {
     log.error('ol', 'Server failed to start: ' + err.message);