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

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')
+        })));
+      }));
+  });
 };

index.js

@@ -37,7 +37,7 @@ var parseExtensions = ['js', 'jsx', 'es5', 'es6'];
  */
 function pipeline() {
   var elements = arguments;
-  return function (comment) {
+  return comment => {
     for (var i = 0; comment && i < elements.length; i++) {
       if (elements[i]) {
         comment = elements[i](comment);
@@ -53,19 +53,15 @@ function pipeline() {
  *
  * @param {Array<string>|string} indexes files to process
  * @param {Object} options options
- * @param {Function} callback called with results
- * @returns {undefined}
+ * @returns {Promise} promise with results
  */
-function expandInputs(indexes, options, callback) {
-  var inputFn;
-  if (options.polyglot || options.shallow || options.documentExported) {
-    inputFn = shallow;
-  } else {
-    inputFn = dependency;
-  }
+function expandInputs(indexes, options) {
   options.parseExtensions = parseExtensions
     .concat(options.parseExtension || []);
-  inputFn(indexes, options, callback);
+  if (options.polyglot || options.shallow || options.documentExported) {
+    return shallow(indexes, options);
+  }
+  return dependency(indexes, options);
 }
 
 /**
@@ -108,27 +104,21 @@ function expandConfig(options) {
  * methods named like `_myMethod` as private.
  * @param {string|Array<string>} [options.extension] treat additional file extensions
  * as JavaScript, extending the default set of `js`, `es6`, and `jsx`.
- * @param {Function} callback to be called when the documentation generation
- * is complete, with (err, result) argumentsj
- * @returns {undefined} calls callback
+ * @returns {Promise} results
  * @public
  * @example
  * var documentation = require('documentation');
  *
  * documentation.build(['index.js'], {
- *
  *   // only output comments with an explicit @public tag
  *   access: ['public']
- *
- * }, function (err, res) {
- *
+ * }).then(res => {
  *   // res is an array of parsed comments with inferred properties
  *   // and more: everything you need to build documentation or
  *   // any other kind of code data.
- *
  * });
  */
-function build(indexes, options, callback) {
+function build(indexes, options) {
   options = options || {};
 
   expandConfig(options);
@@ -137,19 +127,8 @@ function build(indexes, options, callback) {
     indexes = [indexes];
   }
 
-  return expandInputs(indexes, options, function (error, inputs) {
-    if (error) {
-      return callback(error);
-    }
-
-    var result;
-    try {
-      result = buildSync(inputs, options);
-    } catch (e) {
-      return callback(e);
-    }
-    callback(null, result);
-  });
+  return expandInputs(indexes, options).then(inputs =>
+    buildSync(inputs, options));
 }
 
 /**
@@ -258,15 +237,10 @@ function buildSync(indexes, options) {
  * methods named like `_myMethod` as private.
  * @param {string|Array<string>} [options.extension] treat additional file extensions
  * as JavaScript, extending the default set of `js`, `es6`, and `jsx`.
- * @param {Function} callback to be called when the documentation generation
- * is complete, with (err, result) arguments
- * @returns {undefined} calls callback
+ * @returns {Promise} promise with lint results
  * @public
  * @example
- * documentation.lint('file.js', {}, function (err, lintOutput) {
- *   if (err) {
- *     throw err;
- *   }
+ * documentation.lint('file.js').then(lintOutput => {
  *   if (lintOutput) {
  *     console.log(lintOutput);
  *     process.exit(1);
@@ -275,7 +249,7 @@ function buildSync(indexes, options) {
  *   }
  * });
  */
-function lint(indexes, options, callback) {
+function lint(indexes, options) {
   options = options || {};
 
   expandConfig(options);
@@ -299,35 +273,27 @@ function lint(indexes, options, callback) {
     inferType(),
     nest);
 
-  return expandInputs(indexes, options, function (error, inputs) {
-    if (error) {
-      return callback(error);
-    }
-    callback(null,
-      formatLint(hierarchy(
-        inputs
-          .reduce(function (memo, file) {
-            return memo.concat(parseFn(file, options).map(lintPipeline));
-          }, [])
-          .filter(Boolean))));
-  });
+  return expandInputs(indexes, options).then(inputs =>
+    formatLint(hierarchy(
+      inputs
+        .reduce((memo, file) =>
+          memo.concat(parseFn(file, options).map(lintPipeline)), [])
+        .filter(Boolean))));
 }
 
 /**
  * Documentation's formats are modular methods that take comments
- * and options as input and call a callback with writable objects,
+ * and options as input and return Promises with results,
  * like stringified JSON, markdown strings, or Vinyl objects for HTML
  * output.
  * @public
  */
 var formats = {
   html: require('./lib/output/html'),
   md: require('./lib/output/markdown'),
-  remark: function (comments, options, callback) {
-    markdownAST(comments, options, function (err, res) {
-      callback(err, JSON.stringify(res, null, 2));
-    });
-  },
+  remark: (comments, options) =>
+    markdownAST(comments, options)
+      .then(res => JSON.stringify(res, null, 2)),
   json: require('./lib/output/json')
 };
 

lib/commands/build.js

@@ -48,44 +48,44 @@ module.exports.builder = extend({},
  * The former case, with the callback, is used by the `serve` command, which is
  * just a thin wrapper around this one.
  */
-module.exports.handler = function build(argv, callback) {
+module.exports.handler = function build(argv) {
   argv._handled = true;
   argv = sharedOptions.expandInputs(argv);
   if (argv.f === 'html' && argv.o === 'stdout') {
     throw new Error('The HTML output mode requires a destination directory set with -o');
   }
 
-  var generator = documentation.build
-    .bind(null, argv.input, argv, onDocumented);
+  var formatterOptions = {
+    name: argv.name || (argv.package || {}).name,
+    version: argv['project-version'] || (argv.package || {}).version,
+    theme: argv.theme,
+    paths: argv.paths,
+    markdownToc: argv.markdownToc,
+    hljs: argv.hljs || {}
+  };
 
-  function onDocumented(err, comments) {
-    if (err) {
-      if (typeof callback === 'function') {
-        return callback(err);
-      }
-      throw err;
-    }
-
-    var formatterOptions = {
-      name: argv.name || (argv.package || {}).name,
-      version: argv['project-version'] || (argv.package || {}).version,
-      theme: argv.theme,
-      paths: argv.paths,
-      markdownToc: argv.markdownToc,
-      hljs: argv.hljs || {}
-    };
-
-    documentation.formats[argv.format](comments, formatterOptions, onFormatted);
+  function generator() {
+    return documentation.build(argv.input, argv)
+      .then(comments =>
+        documentation.formats[argv.format](comments, formatterOptions)
+        .then(onFormatted))
+      .catch(err => {
+        /* eslint no-console: 0 */
+        console.error(err);
+        process.exit(1);
+      });
   }
 
-  function onFormatted(err, output) {
+  function onFormatted(output) {
     if (argv.watch) {
       updateWatcher();
     }
 
-    if (typeof callback === 'function') {
-      callback(null, output);
-    } else if (argv.output === 'stdout') {
+    if (argv.output === undefined) {
+      return;
+    }
+
+    if (argv.output === 'stdout') {
       process.stdout.write(output);
     } else if (Array.isArray(output)) {
       streamArray(output).pipe(vfs.dest(argv.output));
@@ -98,15 +98,15 @@ module.exports.handler = function build(argv, callback) {
     var watcher = chokidar.watch(argv.input);
     watcher.on('all', debounce(generator, 300));
   }
-  generator();
 
   function updateWatcher() {
     documentation.expandInputs(argv.input, argv, addNewFiles);
   }
 
   function addNewFiles(err, files) {
-    watcher.add(files.map(function (data) {
-      return typeof data === 'string' ? data : data.file;
-    }));
+    watcher.add(files.map(data =>
+      typeof data === 'string' ? data : data.file));
   }
+
+  return generator();
 };

lib/commands/lint.js

@@ -20,15 +20,16 @@ module.exports.builder = {};
 module.exports.handler = function (argv) {
   argv._handled = true;
   argv = sharedOptions.expandInputs(argv);
-  documentation.lint(argv.input, argv, function (err, lintOutput) {
-    if (err) {
-      throw err;
-    }
+  documentation.lint(argv.input, argv).then(lintOutput => {
     if (lintOutput) {
       console.log(lintOutput);
       process.exit(1);
     } else {
       process.exit(0);
     }
+  }, err => {
+    /* eslint no-console: 0 */
+    console.error(err);
+    process.exit(1);
   });
 };