Replace documentation with jsdoc with mocha flavor

docs/API.md

@@ -0,0 +1,20 @@
+# Mocha's API Documentation
+
+* * *
+
+Congratulations!  You've found Mocha's API documentation.  These docs are for developers who wish to:
+
+- Create an extension for Mocha, or
+- Develop Mocha itself, or
+- Do something else fancy with Mocha
+
+Otherwise, **you probably want the [main documentation](https://mochajs.org)**.
+
+## Other Links
+
+- **[Main Documentation](https://mochajs.org)**
+- **[Release Notes / History / Changes](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md)**
+- [Code of Conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md)
+- [Gitter Chatroom](https://gitter.im/mochajs/mocha) (ask questions here!)
+- [Google Group](https://groups.google.com/group/mochajs)
+- [Issue Tracker](https://github.com/mochajs/mocha/issues)

docs/_config.yml

@@ -3,6 +3,7 @@ exclude:
   - README.md
   - .*
   - LICENSE*
+  - API.md
 repository: mochajs/mocha
 source: docs
 

jsdoc.conf.json

@@ -0,0 +1,32 @@
+{
+  "tags": {
+    "allowUnknownTags": true
+  },
+  "source": {
+    "include": ["lib/", "./docs/API.md"]
+  },
+  "plugins": ["plugins/markdown"],
+  "opts": {
+    "encoding": "utf8",
+    "template": "node_modules/@mocha/docdash",
+    "destination": "docs/api",
+    "recurse": true,
+    "verbose": true
+  },
+  "markdown": {
+    "parser": "gfm",
+    "hardwrap": true
+  },
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": false,
+    "default": {
+      "outputSourceFiles": true,
+      "includeDate": false
+    }
+  },
+  "mocha-docdash": {
+    "static": false,
+    "sort": true
+  }
+}

lib/hook.js

@@ -1,11 +1,4 @@
 'use strict';
-/**
- * @module Hook
- *
- */
-/**
- * Module dependencies.
- */
 
 var Runnable = require('./runnable');
 var inherits = require('./utils').inherits;
@@ -17,15 +10,12 @@ var inherits = require('./utils').inherits;
 module.exports = Hook;
 
 /**
- * Initialize a new `Hook` with the given `title` and callback `fn`. Derived from
- * `Runnable`.
+ * Initialize a new `Hook` with the given `title` and callback `fn`
  *
- * @memberof Mocha
- * @public
  * @class
+ * @extends Runnable
  * @param {String} title
  * @param {Function} fn
- * @api private
  */
 function Hook (title, fn) {
   Runnable.call(this, title, fn);
@@ -40,11 +30,10 @@ inherits(Hook, Runnable);
 /**
  * Get or set the test `err`.
  *
- * @memberof Mocha.Hook
+ * @memberof Hook
  * @public
  * @param {Error} err
  * @return {Error}
- * @api public
  */
 Hook.prototype.error = function (err) {
   if (!arguments.length) {

lib/interfaces/bdd.js

@@ -1,9 +1,5 @@
 'use strict';
 
-/**
- * Module dependencies.
- */
-
 var Test = require('../test');
 
 /**
@@ -23,7 +19,7 @@ var Test = require('../test');
  *
  * @param {Suite} suite Root suite.
  */
-module.exports = function (suite) {
+module.exports = function bddInterface (suite) {
   var suites = [suite];
 
   suite.on('pre-require', function (context, file, mocha) {

lib/interfaces/exports.js

@@ -1,9 +1,4 @@
 'use strict';
-
-/**
- * Module dependencies.
- */
-
 var Suite = require('../suite');
 var Test = require('../test');
 

lib/interfaces/qunit.js

@@ -1,9 +1,5 @@
 'use strict';
 
-/**
- * Module dependencies.
- */
-
 var Test = require('../test');
 
 /**
@@ -31,7 +27,7 @@ var Test = require('../test');
  *
  * @param {Suite} suite Root suite.
  */
-module.exports = function (suite) {
+module.exports = function qUnitInterface (suite) {
   var suites = [suite];
 
   suite.on('pre-require', function (context, file, mocha) {

lib/interfaces/tdd.js

@@ -1,9 +1,5 @@
 'use strict';
 
-/**
- * Module dependencies.
- */
-
 var Test = require('../test');
 
 /**

lib/mocha.js

@@ -5,23 +5,12 @@
  * Copyright(c) 2011 TJ Holowaychuk <tj@vision-media.ca>
  * MIT Licensed
  */
-/**
- * @namespace Mocha
- * @module Mocha
- */
-/**
- * Module dependencies.
- */
 
 var escapeRe = require('escape-string-regexp');
 var path = require('path');
 var reporters = require('./reporters');
 var utils = require('./utils');
 
-/**
- * Expose `Mocha`.
- */
-
 exports = module.exports = Mocha;
 
 /**
@@ -64,7 +53,7 @@ exports.Test = require('./test');
 /**
  * Return image `name` path.
  *
- * @api private
+ * @private
  * @param {string} name
  * @return {string}
  */
@@ -88,10 +77,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
  */
 function Mocha (options) {
   options = options || {};

lib/pending.js

@@ -1,9 +1,5 @@
 'use strict';
 
-/**
- * Expose `Pending`.
- */
-
 module.exports = Pending;
 
 /**

lib/runnable.js

@@ -1,10 +1,4 @@
 'use strict';
-/**
- * @module Runnable
- */
-/**
- * Module dependencies.
- */
 var EventEmitter = require('events').EventEmitter;
 var Pending = require('./pending');
 var debug = require('debug')('mocha:runnable');
@@ -23,24 +17,15 @@ var clearTimeout = global.clearTimeout;
 var clearInterval = global.clearInterval;
 /* eslint-enable no-unused-vars, no-native-reassign */
 
-/**
- * Object#toString().
- */
-
 var toString = Object.prototype.toString;
 
-/**
- * Expose `Runnable`.
- */
-
 module.exports = Runnable;
 
 /**
  * Initialize a new `Runnable` with the given `title` and callback `fn`.  Derived from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
  *
- * @memberof Mocha
- * @public
  * @class
+ * @extends EventEmitter
  * @param {String} title
  * @param {Function} fn
  */

lib/test.js

@@ -1,23 +1,15 @@
 'use strict';
-
-/**
- * Module dependencies.
- */
-
 var Runnable = require('./runnable');
 var utils = require('./utils');
 var isString = utils.isString;
 
-/**
- * Expose `Test`.
- */
-
 module.exports = Test;
 
 /**
  * Initialize a new `Test` with the given `title` and callback `fn`.
  *
- * @api private
+ * @class
+ * @extends Runnable
  * @param {String} title
  * @param {Function} fn
  */