From e9e0292fa02842e06c5b29977306cfdd1473f676 Mon Sep 17 00:00:00 2001 From: Craig Taub Date: Tue, 23 Jun 2020 14:58:01 +0100 Subject: [PATCH 1/4] Remove globals in api docs --- lib/browser/progress.js | 4 ++++ lib/cli/collect-files.js | 1 + lib/interfaces/common.js | 5 +++++ lib/mocha.js | 9 +++++++++ lib/nodejs/parallel-buffered-runner.js | 2 ++ lib/nodejs/serializer.js | 2 ++ lib/pending.js | 4 ++++ lib/runnable.js | 4 ++++ lib/runner.js | 4 ++++ lib/suite.js | 4 ++++ 10 files changed, 39 insertions(+) diff --git a/lib/browser/progress.js b/lib/browser/progress.js index 553fc6eb56..3838cdc0ed 100644 --- a/lib/browser/progress.js +++ b/lib/browser/progress.js @@ -1,5 +1,9 @@ 'use strict'; +/** + @module Progress +*/ + /** * Expose `Progress`. */ diff --git a/lib/cli/collect-files.js b/lib/cli/collect-files.js index 5dc5e1fc99..551d5138e4 100644 --- a/lib/cli/collect-files.js +++ b/lib/cli/collect-files.js @@ -81,6 +81,7 @@ module.exports = ({ignore, extension, file, recursive, sort, spec} = {}) => { /** * An object to configure how Mocha gathers test files + * @private * @typedef {Object} FileCollectionOptions * @property {string[]} extension - File extensions to use * @property {string[]} spec - Files, dirs, globs to run diff --git a/lib/interfaces/common.js b/lib/interfaces/common.js index 3c171ef8d7..663948d7ef 100644 --- a/lib/interfaces/common.js +++ b/lib/interfaces/common.js @@ -1,5 +1,9 @@ 'use strict'; +/** + @module common +*/ + var Suite = require('../suite'); var errors = require('../errors'); var createMissingArgumentError = errors.createMissingArgumentError; @@ -9,6 +13,7 @@ var createForbiddenExclusivityError = errors.createForbiddenExclusivityError; /** * Functions common to more than one interface. * + * @private * @param {Suite[]} suites * @param {Context} context * @param {Mocha} mocha diff --git a/lib/mocha.js b/lib/mocha.js index 8aabcb8762..ee76ba1d50 100644 --- a/lib/mocha.js +++ b/lib/mocha.js @@ -35,23 +35,28 @@ exports = module.exports = Mocha; /** * A Mocha instance is a finite state machine. * These are the states it can be in. + * @private */ var mochaStates = utils.defineConstants({ /** * Initial state of the mocha instance + * @private */ INIT: 'init', /** * Mocha instance is running tests + * @private */ RUNNING: 'running', /** * Mocha instance is done running tests and references to test functions and hooks are cleaned. * You can reset this state by unloading the test files. + * @private */ REFERENCES_CLEANED: 'referencesCleaned', /** * Mocha instance is disposed and can no longer be used. + * @private */ DISPOSED: 'disposed' }); @@ -67,6 +72,7 @@ if (!utils.isBrowser() && typeof module.paths !== 'undefined') { /** * Expose internals. + * @private */ exports.utils = utils; @@ -921,6 +927,7 @@ Object.defineProperty(Mocha.prototype, 'version', { /** * Callback to be invoked when test execution is complete. * + * @private * @callback DoneCB * @param {number} failures - Number of failures that occurred. */ @@ -1091,6 +1098,7 @@ Mocha.prototype.lazyLoadFiles = function lazyLoadFiles(enable) { /** * An alternative way to define root hooks that works with parallel runs. + * @private * @typedef {Object} MochaRootHookObject * @property {Function|Function[]} [beforeAll] - "Before all" hook(s) * @property {Function|Function[]} [beforeEach] - "Before each" hook(s) @@ -1100,6 +1108,7 @@ Mocha.prototype.lazyLoadFiles = function lazyLoadFiles(enable) { /** * An function that returns a {@link MochaRootHookObject}, either sync or async. + * @private * @callback MochaRootHookFunction * @returns {MochaRootHookObject|Promise} */ diff --git a/lib/nodejs/parallel-buffered-runner.js b/lib/nodejs/parallel-buffered-runner.js index d31929804a..ee8635ab98 100644 --- a/lib/nodejs/parallel-buffered-runner.js +++ b/lib/nodejs/parallel-buffered-runner.js @@ -281,12 +281,14 @@ module.exports = ParallelBufferedRunner; /** * Listener function intended to be bound to `Process.SIGINT` event + * @private * @callback SigIntListener * @returns {Promise} */ /** * A function accepting a test file path and returning the results of a test run + * @private * @callback FileRunner * @param {string} filename - File to run * @returns {Promise} diff --git a/lib/nodejs/serializer.js b/lib/nodejs/serializer.js index dae366ce79..ac95bdc344 100644 --- a/lib/nodejs/serializer.js +++ b/lib/nodejs/serializer.js @@ -387,6 +387,7 @@ exports.SerializableWorkerResult = SerializableWorkerResult; /** * The result of calling `SerializableEvent.serialize`, as received * by the deserializer. + * @private * @typedef {Object} SerializedEvent * @property {object?} data - Optional serialized data * @property {object?} error - Optional serialized `Error` @@ -395,6 +396,7 @@ exports.SerializableWorkerResult = SerializableWorkerResult; /** * The result of calling `SerializableWorkerResult.serialize` as received * by the deserializer. + * @private * @typedef {Object} SerializedWorkerResult * @property {number} failureCount - Number of failures * @property {SerializedEvent[]} events - Serialized events diff --git a/lib/pending.js b/lib/pending.js index bb9a505337..cf9cc84a0e 100644 --- a/lib/pending.js +++ b/lib/pending.js @@ -1,5 +1,9 @@ 'use strict'; +/** + @module Pending +*/ + module.exports = Pending; /** diff --git a/lib/runnable.js b/lib/runnable.js index 342152c3c2..e1de63df47 100644 --- a/lib/runnable.js +++ b/lib/runnable.js @@ -1,5 +1,9 @@ 'use strict'; +/** + @module Runnable +*/ + var EventEmitter = require('events').EventEmitter; var Pending = require('./pending'); var debug = require('debug')('mocha:runnable'); diff --git a/lib/runner.js b/lib/runner.js index 22e7bb91d6..4b6e067c5c 100644 --- a/lib/runner.js +++ b/lib/runner.js @@ -1,5 +1,9 @@ 'use strict'; +/** + @module Runner +*/ + /** * Module dependencies. */ diff --git a/lib/suite.js b/lib/suite.js index 24e6dd344e..d7a139bbde 100644 --- a/lib/suite.js +++ b/lib/suite.js @@ -1,5 +1,9 @@ 'use strict'; +/** + @module Suite +*/ + /** * Module dependencies. */ From 49544ae562a0e275425927ba35bcb86533423b53 Mon Sep 17 00:00:00 2001 From: Craig Taub Date: Tue, 23 Jun 2020 16:44:49 +0100 Subject: [PATCH 2/4] Fix runnable + suite --- lib/runnable.js | 5 +---- lib/suite.js | 5 +---- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/lib/runnable.js b/lib/runnable.js index e1de63df47..023481dd69 100644 --- a/lib/runnable.js +++ b/lib/runnable.js @@ -1,9 +1,5 @@ 'use strict'; -/** - @module Runnable -*/ - var EventEmitter = require('events').EventEmitter; var Pending = require('./pending'); var debug = require('debug')('mocha:runnable'); @@ -15,6 +11,7 @@ var createMultipleDoneError = errors.createMultipleDoneError; /** * Save timer references to avoid Sinon interfering (see GH-237). + * @private */ var Date = global.Date; var setTimeout = global.setTimeout; diff --git a/lib/suite.js b/lib/suite.js index d7a139bbde..e9d45d94c4 100644 --- a/lib/suite.js +++ b/lib/suite.js @@ -1,11 +1,8 @@ 'use strict'; -/** - @module Suite -*/ - /** * Module dependencies. + * @private */ var EventEmitter = require('events').EventEmitter; var Hook = require('./hook'); From 3ebca7e142fbaf27ff234ce2a44042bdb270d5b4 Mon Sep 17 00:00:00 2001 From: Craig Taub Date: Tue, 23 Jun 2020 16:49:52 +0100 Subject: [PATCH 3/4] Fix Runner issues --- lib/runner.js | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/lib/runner.js b/lib/runner.js index 4b6e067c5c..1214121e1e 100644 --- a/lib/runner.js +++ b/lib/runner.js @@ -1,11 +1,8 @@ 'use strict'; -/** - @module Runner -*/ - /** * Module dependencies. + * @private */ var util = require('util'); var EventEmitter = require('events').EventEmitter; @@ -35,6 +32,7 @@ var createFatalError = errors.createFatalError; /** * Non-enumerable globals. + * @private * @readonly */ var globals = [ From 0c49a54837a2b96e127dfab2657810290ab936c7 Mon Sep 17 00:00:00 2001 From: Craig Taub Date: Thu, 2 Jul 2020 10:10:20 +0100 Subject: [PATCH 4/4] rename @module tags 2 b filepaths from /lib --- lib/browser/progress.js | 2 +- lib/interfaces/common.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/browser/progress.js b/lib/browser/progress.js index 3838cdc0ed..72ce5c57c1 100644 --- a/lib/browser/progress.js +++ b/lib/browser/progress.js @@ -1,7 +1,7 @@ 'use strict'; /** - @module Progress + @module browser/Progress */ /** diff --git a/lib/interfaces/common.js b/lib/interfaces/common.js index 663948d7ef..f5ae760c9b 100644 --- a/lib/interfaces/common.js +++ b/lib/interfaces/common.js @@ -1,7 +1,7 @@ 'use strict'; /** - @module common + @module interfaces/common */ var Suite = require('../suite');