feat(core): Switch to Promises everywhere. Adopt Node v4 ES6

Big changes:

* Uses template strings where appropriate
* Config and argument parsing is unified and there is no such thing
  as formatterOptions anymore. All user-passed options go through
  mergeConfig.

Author: tmcw

.eslintrc

@@ -38,7 +38,6 @@
   "extends": "eslint:recommended",
   "env": {
     "node": true,
-    "es6": true,
-    "browser": true
+    "es6": true
   }
 }

README.md

@@ -46,21 +46,21 @@ lets you run `documentation` as a [Gulp](http://gulpjs.com/) build task.
 
 ## Examples
 
-* [HTML output with default template](http://documentation.js.org/html-example/)
-* [Markdown](https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md)
-* [JSON](http://documentation.js.org/html-example/index.json)
+-   [HTML output with default template](http://documentation.js.org/html-example/)
+-   [Markdown](https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md)
+-   [JSON](http://documentation.js.org/html-example/index.json)
 
 ## Documentation
 
-* [Getting Started](docs/GETTING_STARTED.md): start here
-* [Usage](docs/USAGE.md): how to use documentation.js
-* [Recipes](docs/RECIPES.md): tricks for writing effective JSDoc docs
-* [Node API](docs/NODE_API.md): documentation.js's self-generated documentation
-* [Configuring documentation.js](docs/CONFIG.md)
-* [FAQ](docs/FAQ.md)
-* [Troubleshooting](docs/TROUBLESHOOTING.md)
-* [Theming](docs/THEMING.md): tips for theming documentation output in HTML
-* [See also](https://github.com/documentationjs/documentation/wiki/See-also): a list of projects similar to documentation.js
+-   [Getting Started](docs/GETTING_STARTED.md): start here
+-   [Usage](docs/USAGE.md): how to use documentation.js
+-   [Recipes](docs/RECIPES.md): tricks for writing effective JSDoc docs
+-   [Node API](docs/NODE_API.md): documentation.js's self-generated documentation
+-   [Configuring documentation.js](docs/CONFIG.md)
+-   [FAQ](docs/FAQ.md)
+-   [Troubleshooting](docs/TROUBLESHOOTING.md)
+-   [Theming](docs/THEMING.md): tips for theming documentation output in HTML
+-   [See also](https://github.com/documentationjs/documentation/wiki/See-also): a list of projects similar to documentation.js
 
 ## User Guide
 
@@ -116,9 +116,9 @@ _We have plenty of
 [issues](https://github.com/documentationjs/documentation/issues) that we'd
 love help with._
 
-* Robust and complete `JSDoc` support, including typedefs.
-* Strong support for HTML and Markdown output
-* Documentation coverage, statistics, and validation
+-   Robust and complete `JSDoc` support, including typedefs.
+-   Strong support for HTML and Markdown output
+-   Documentation coverage, statistics, and validation
 
 documentation is an OPEN Open Source Project. This means that:
 

bin/documentation.js

@@ -24,28 +24,28 @@ var argv = yargs
   .version(function () {
     return require('../package').version;
   })
-  .usage('Usage:\n\n' +
-    '# generate markdown docs for index.js and files it references\n' +
-    '$0 build index.js -f md\n\n' +
+  .usage(`Usage:
+  # generate markdown docs for index.js and files it references 
+  $0 build index.js -f md 
 
-    '# generate html docs for all files in src\n' +
-    '$0 build src/** -f html -o docs\n\n' +
+  # generate html docs for all files in src 
+  $0 build src/** -f html -o docs 
 
-    '# document index.js, ignoring any files it requires or imports\n' +
-    '$0 build index.js -f md --shallow\n\n' +
+  # document index.js, ignoring any files it requires or imports 
+  $0 build index.js -f md --shallow 
 
-    '# build, serve, and live-update html docs for app.js\n' +
-    '$0 serve app.js\n\n' +
+  # build, serve, and live-update html docs for app.js 
+  $0 serve app.js 
 
-    '# validate JSDoc syntax in util.js\n' +
-    '$0 lint util.js\n\n' +
+  # validate JSDoc syntax in util.js 
+  $0 lint util.js 
 
-    '# update the API section of README.md with docs from index.js\n' +
-    '$0 readme index.js --section=API\n\n' +
+  # update the API section of README.md with docs from index.js 
+  $0 readme index.js --section=API 
 
-    '# build docs for all values exported by index.js\n' +
-    '$0 build --document-exported index.js'
-  )
+  # build docs for all values exported by index.js 
+  $0 build --document-exported index.js
+`)
   .recommendCommands()
   .help()
   .argv;

default_theme/index.js

@@ -11,7 +11,7 @@ var fs = require('fs'),
   createLinkerStack = require('../').util.createLinkerStack,
   hljs = require('highlight.js');
 
-module.exports = function (comments, options, callback) {
+module.exports = function (comments, options) {
 
   var linkerStack = createLinkerStack(options)
     .namespaceResolver(comments, function (namespace) {
@@ -79,14 +79,16 @@ module.exports = function (comments, options, callback) {
   var pageTemplate = _.template(fs.readFileSync(path.join(__dirname, 'index._'), 'utf8'),  sharedImports);
 
   // push assets into the pipeline as well.
-  vfs.src([__dirname + '/assets/**'], { base: __dirname })
-    .pipe(concat(function (files) {
-      callback(null, files.concat(new File({
-        path: 'index.html',
-        contents: new Buffer(pageTemplate({
-          docs: comments,
-          options: options
-        }), 'utf8')
-      })));
-    }));
+  return new Promise(resolve => {
+    vfs.src([__dirname + '/assets/**'], { base: __dirname })
+      .pipe(concat(function (files) {
+        resolve(files.concat(new File({
+          path: 'index.html',
+          contents: new Buffer(pageTemplate({
+            docs: comments,
+            options: options
+          }), 'utf8')
+        })));
+      }));
+  });
 };