Implement API documentation using npm:documantation.

Fixes #3138
Replaces and closes #3239

basically working

Suite and utils work

Runner and Suite datatypes work

Hook extends Runnable - at least link in description

hook is child of mocha and has error

first solid pass

Remove attempted module link from Hook to Runnable because of documentationjs/documentation#820

Switch API documenation to html output, link to them, include in site build

Update TOC

Bring lock file in sync with package.json

Linting

Update package-lock.json

.gitignore

@@ -21,5 +21,5 @@ yarn.lock
 *_REMOTE_*
 docs/_site
 docs/_dist
+docs/api
 .vscode/
-

docs/index.md

@@ -52,6 +52,7 @@ Mocha is a feature-rich JavaScript test framework running on [Node.js](https://n
 
 - [Installation](#installation)
 - [Getting Started](#getting-started)
+- [Detects Multiple Calls to `done()`](#detects-multiple-calls-to-done)
 - [Assertions](#assertions)
 - [Asynchronous Code](#asynchronous-code)
 - [Synchronous Code](#synchronous-code)
@@ -1343,4 +1344,4 @@ $ REPORTER=nyan npm test
 
 ## More Information
 
-In addition to chatting with us on [Gitter](https://gitter.im/mochajs/mocha), for additional information such as using spies, mocking, and shared behaviours be sure to check out the [Mocha Wiki](https://github.com/mochajs/mocha/wiki) on GitHub. For discussions join the [Google Group](https://groups.google.com/group/mochajs). For a running example of Mocha, view [example/tests.html](example/tests.html). For the JavaScript API, view the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js#L51).
+In addition to chatting with us on [Gitter](https://gitter.im/mochajs/mocha), for additional information such as using spies, mocking, and shared behaviours be sure to check out the [Mocha Wiki](https://github.com/mochajs/mocha/wiki) on GitHub. For discussions join the [Google Group](https://groups.google.com/group/mochajs). For a running example of Mocha, view [example/tests.html](example/tests.html). For the JavaScript API, view the [API documentation](api/) or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js#L51).

lib/context.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Context
+ */
 /**
  * Expose `Context`.
  */
@@ -18,7 +20,7 @@ function Context () {}
  *
  * @api private
  * @param {Runnable} runnable
- * @return {Context}
+ * @return {Context} context
  */
 Context.prototype.runnable = function (runnable) {
   if (!arguments.length) {

lib/hook.js

@@ -1,5 +1,8 @@
 'use strict';
-
+/**
+ * @module Hook
+ *
+ */
 /**
  * Module dependencies.
  */
@@ -14,8 +17,12 @@ var inherits = require('./utils').inherits;
 module.exports = Hook;
 
 /**
- * Initialize a new `Hook` with the given `title` and callback `fn`.
+ * Initialize a new `Hook` with the given `title` and callback `fn`. Derived from
+ * `Runnable`.
  *
+ * @memberof Mocha
+ * @public
+ * @class
  * @param {String} title
  * @param {Function} fn
  * @api private
@@ -33,6 +40,8 @@ inherits(Hook, Runnable);
 /**
  * Get or set the test `err`.
  *
+ * @memberof Mocha.Hook
+ * @public
  * @param {Error} err
  * @return {Error}
  * @api public

lib/mocha.js

@@ -5,7 +5,10 @@
  * Copyright(c) 2011 TJ Holowaychuk <tj@vision-media.ca>
  * MIT Licensed
  */
-
+/**
+ * @namespace Mocha
+ * @module Mocha
+ */
 /**
  * Module dependencies.
  */
@@ -34,11 +37,25 @@ if (!process.browser) {
  * Expose internals.
  */
 
+/**
+ * @public
+ * @class utils
+ * @memberof Mocha
+ */
 exports.utils = utils;
 exports.interfaces = require('./interfaces');
+/**
+ *
+ * @memberof Mocha
+ * @public
+ */
 exports.reporters = reporters;
 exports.Runnable = require('./runnable');
 exports.Context = require('./context');
+/**
+ *
+ * @memberof Mocha
+ */
 exports.Runner = require('./runner');
 exports.Suite = require('./suite');
 exports.Hook = require('./hook');
@@ -71,6 +88,8 @@ function image (name) {
  *   - `fullTrace` display the full stack-trace on failing
  *   - `grep` string or regexp to filter tests with
  *
+ * @public
+ * @class Mocha
  * @param {Object} options
  * @api public
  */
@@ -106,6 +125,7 @@ function Mocha (options) {
 /**
  * Enable or disable bailing on the first failure.
  *
+ * @public
  * @api public
  * @param {boolean} [bail]
  */
@@ -120,6 +140,7 @@ Mocha.prototype.bail = function (bail) {
 /**
  * Add test `file`.
  *
+ * @public
  * @api public
  * @param {string} file
  */
@@ -131,6 +152,7 @@ Mocha.prototype.addFile = function (file) {
 /**
  * Set reporter to `reporter`, defaults to "spec".
  *
+ * @public
  * @param {String|Function} reporter name or constructor
  * @param {Object} reporterOptions optional options
  * @api public
@@ -181,7 +203,7 @@ Mocha.prototype.reporter = function (reporter, reporterOptions) {
 
 /**
  * Set test UI `name`, defaults to "bdd".
- *
+ * @public
  * @api public
  * @param {string} bdd
  */
@@ -260,6 +282,7 @@ Mocha.prototype._growl = function (runner, reporter) {
 /**
  * Escape string and add it to grep as a regexp.
  *
+ * @public
  * @api public
  * @param str
  * @returns {Mocha}
@@ -271,6 +294,7 @@ Mocha.prototype.fgrep = function (str) {
 /**
  * Add regexp to grep, if `re` is a string it is escaped.
  *
+ * @public
  * @param {RegExp|String} re
  * @return {Mocha}
  * @api public
@@ -290,6 +314,7 @@ Mocha.prototype.grep = function (re) {
 /**
  * Invert `.grep()` matches.
  *
+ * @public
  * @return {Mocha}
  * @api public
  */
@@ -301,6 +326,7 @@ Mocha.prototype.invert = function () {
 /**
  * Ignore global leaks.
  *
+ * @public
  * @param {Boolean} ignore
  * @return {Mocha}
  * @api public
@@ -317,6 +343,7 @@ Mocha.prototype.ignoreLeaks = function (ignore) {
  *
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.checkLeaks = function () {
   this.options.ignoreLeaks = false;
@@ -328,6 +355,7 @@ Mocha.prototype.checkLeaks = function () {
  *
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.fullTrace = function () {
   this.options.fullStackTrace = true;
@@ -339,6 +367,7 @@ Mocha.prototype.fullTrace = function () {
  *
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.growl = function () {
   this.options.growl = true;
@@ -351,6 +380,7 @@ Mocha.prototype.growl = function () {
  * @param {Array|String} globals
  * @return {Mocha}
  * @api public
+ * @public
  * @param {Array|string} globals
  * @return {Mocha}
  */
@@ -365,6 +395,7 @@ Mocha.prototype.globals = function (globals) {
  * @param {Boolean} colors
  * @return {Mocha}
  * @api public
+ * @public
  * @param {boolean} colors
  * @return {Mocha}
  */
@@ -381,6 +412,7 @@ Mocha.prototype.useColors = function (colors) {
  * @param {Boolean} inlineDiffs
  * @return {Mocha}
  * @api public
+ * @public
  * @param {boolean} inlineDiffs
  * @return {Mocha}
  */
@@ -395,6 +427,7 @@ Mocha.prototype.useInlineDiffs = function (inlineDiffs) {
  * @param {Boolean} hideDiff
  * @return {Mocha}
  * @api public
+ * @public
  * @param {boolean} hideDiff
  * @return {Mocha}
  */
@@ -409,6 +442,7 @@ Mocha.prototype.hideDiff = function (hideDiff) {
  * @param {Number} timeout
  * @return {Mocha}
  * @api public
+ * @public
  * @param {number} timeout
  * @return {Mocha}
  */
@@ -423,6 +457,7 @@ Mocha.prototype.timeout = function (timeout) {
  * @param {Number} retry times
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.retries = function (n) {
   this.suite.retries(n);
@@ -435,6 +470,7 @@ Mocha.prototype.retries = function (n) {
  * @param {Number} slow
  * @return {Mocha}
  * @api public
+ * @public
  * @param {number} slow
  * @return {Mocha}
  */
@@ -449,6 +485,7 @@ Mocha.prototype.slow = function (slow) {
  * @param {Boolean} enabled
  * @return {Mocha}
  * @api public
+ * @public
  * @param {boolean} enabled
  * @return {Mocha}
  */
@@ -462,6 +499,7 @@ Mocha.prototype.enableTimeouts = function (enabled) {
  *
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.asyncOnly = function () {
   this.options.asyncOnly = true;
@@ -472,6 +510,7 @@ Mocha.prototype.asyncOnly = function () {
  * Disable syntax highlighting (in browser).
  *
  * @api public
+ * @public
  */
 Mocha.prototype.noHighlighting = function () {
   this.options.noHighlighting = true;
@@ -483,6 +522,7 @@ Mocha.prototype.noHighlighting = function () {
  *
  * @return {Mocha}
  * @api public
+ * @public
  */
 Mocha.prototype.allowUncaught = function () {
   this.options.allowUncaught = true;
@@ -528,6 +568,7 @@ Mocha.prototype.forbidPending = function () {
  * cache first in whichever manner best suits your needs.
  *
  * @api public
+ * @public
  * @param {Function} fn
  * @return {Runner}
  */

lib/ms.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module milliseconds
+ */
 /**
  * Helpers.
  */
@@ -13,6 +15,8 @@ var y = d * 365.25;
 /**
  * Parse or format the given `val`.
  *
+ * @memberof Mocha
+ * @public
  * @api public
  * @param {string|number} val
  * @return {string|number}

lib/reporters/base.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Base
+ */
 /**
  * Module dependencies.
  */
@@ -185,6 +187,9 @@ var generateDiff = exports.generateDiff = function (actual, expected) {
 /**
  * Output the given `failures` as a list.
  *
+ * @public
+ * @memberof Mocha.reporters.Base
+ * @variation 1
  * @param {Array} failures
  * @api public
  */
@@ -261,6 +266,9 @@ exports.list = function (failures) {
  * stats such as test duration, number
  * of tests passed / failed etc.
  *
+ * @memberof Mocha.reporters
+ * @public
+ * @class
  * @param {Runner} runner
  * @api public
  */
@@ -328,6 +336,8 @@ function Base (runner) {
  * Output common epilogue used by many of
  * the bundled reporters.
  *
+ * @memberof Mocha.reporters.Base
+ * @public
  * @api public
  */
 Base.prototype.epilogue = function () {

lib/reporters/doc.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Doc
+ */
 /**
  * Module dependencies.
  */
@@ -16,6 +18,10 @@ exports = module.exports = Doc;
 /**
  * Initialize a new `Doc` reporter.
  *
+ * @class
+ * @memberof Mocha.reporters
+ * @extends {Base}
+ * @public
  * @param {Runner} runner
  * @api public
  */

lib/reporters/dot.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module Dot
+ */
 /**
  * Module dependencies.
  */
@@ -17,6 +19,10 @@ exports = module.exports = Dot;
 /**
  * Initialize a new `Dot` matrix test reporter.
  *
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
+ * @public
  * @api public
  * @param {Runner} runner
  */