From 1e7f07259e102bd0f1ae92080e633abbb8d1c86e Mon Sep 17 00:00:00 2001 From: Steve Gravrock Date: Sat, 8 Apr 2023 12:37:40 -0700 Subject: [PATCH] API docs for parallel support things that jasmine-npm uses --- lib/jasmine-core/jasmine.js | 92 +++++++++++++++++----------- src/core/ParallelReportDispatcher.js | 46 +++++++++++--- src/core/QueueRunner.js | 9 --- src/core/ReportDispatcher.js | 9 --- src/core/Timer.js | 28 ++++++--- 5 files changed, 112 insertions(+), 72 deletions(-) diff --git a/lib/jasmine-core/jasmine.js b/lib/jasmine-core/jasmine.js index 86fa8bd6..58ecb7d0 100644 --- a/lib/jasmine-core/jasmine.js +++ b/lib/jasmine-core/jasmine.js @@ -7110,15 +7110,19 @@ getJasmineRequireObj().NeverSkipPolicy = function(j$) { }; getJasmineRequireObj().ParallelReportDispatcher = function(j$) { - /* - A report dispatcher packaged for convenient use from outside jasmine-core. - - This isn't part of the public interface, but it is used by - jasmine-npm. -core and -npm version in lockstep at the major and minor - levels but version independently at the patch level. Any changes that - would break -npm should be done in a major or minor release, never a - patch release, and accompanied by a change to -npm that's released in - the same version. + /** + * @class ParallelReportDispatcher + * @implements Reporter + * @classdesc A report dispatcher packaged for convenient use from outside jasmine-core. + * + * This is intended to help packages like `jasmine` (the Jasmine runner for + * Node.js) do their own report dispatching in order to support parallel + * execution. If you aren't implementing a runner package that supports + * parallel execution, this class probably isn't what you're looking for. + * + * Warning: Do not use ParallelReportDispatcher in the same process that + * Jasmine specs run in. Doing so will break Jasmine's error handling. + * @param onError {function} Function called when an unhandled exception, unhandled promise rejection, or explicit reporter failure occurs */ function ParallelReportDispatcher(onError, deps = {}) { const ReportDispatcher = deps.ReportDispatcher || j$.ReportDispatcher; @@ -7156,9 +7160,33 @@ getJasmineRequireObj().ParallelReportDispatcher = function(j$) { ); const self = { + /** + * Adds a reporter to the list of reporters that events will be dispatched to. + * @function + * @name ParallelReportDispatcher#addReporter + * @param {Reporter} reporterToAdd The reporter to be added. + * @see custom_reporter + */ addReporter: dispatcher.addReporter.bind(dispatcher), + /** + * Clears all registered reporters. + * @function + * @name ParallelReportDispatcher#clearReporters + */ clearReporters: dispatcher.clearReporters.bind(dispatcher), + /** + * Installs a global error handler. After this method is called, any + * unhandled exceptions or unhandled promise rejections will be passed to + * the onError callback that was passed to the constructor. + * @function + * @name ParallelReportDispatcher#installGlobalErrors + */ installGlobalErrors: globalErrors.install.bind(globalErrors), + /** + * Uninstalls the global error handler. + * @function + * @name ParallelReportDispatcher#uninstallGlobalErrors + */ uninstallGlobalErrors: function() { // late-bind uninstall because it doesn't exist until install is called globalErrors.uninstall(globalErrors); @@ -7536,15 +7564,6 @@ getJasmineRequireObj().makePrettyPrinter = function(j$) { }; getJasmineRequireObj().QueueRunner = function(j$) { - /* - QueueRunner isn't part of the public interface, but it is used by - jasmine-npm. -core and -npm version in lockstep at the major and minor - levels but version independently at the patch level. Any changes that - would break -npm should be done in a major or minor release, never a - patch release, and accompanied by a change to -npm that's released in - the same version. - */ - let nextid = 1; function StopExecutionError() {} @@ -7835,15 +7854,6 @@ getJasmineRequireObj().QueueRunner = function(j$) { }; getJasmineRequireObj().ReportDispatcher = function(j$) { - /* - ReportDispatcher isn't part of the public interface, but it is used by - jasmine-npm. -core and -npm version in lockstep at the major and minor - levels but version independently at the patch level. Any changes that - would break -npm should be done in a major or minor release, never a - patch release, and accompanied by a change to -npm that's released in - the same version. - */ - function ReportDispatcher(methods, queueRunnerFactory, onLateError) { const dispatchedMethods = methods || []; @@ -10376,31 +10386,41 @@ getJasmineRequireObj().SuiteBuilder = function(j$) { }; getJasmineRequireObj().Timer = function() { - /* - Timer isn't part of the public interface, but it is used by - jasmine-npm. -core and -npm version in lockstep at the major and minor - levels but version independently at the patch level. Any changes that - would break -npm should be done in a major or minor release, never a - patch release, and accompanied by a change to -npm that's released in - the same version. - */ - const defaultNow = (function(Date) { return function() { return new Date().getTime(); }; })(Date); + /** + * @class Timer + * @classdesc Tracks elapsed time + * @example + * const timer = new jasmine.Timer(); + * timer.start(); + * const elapsed = timer.elapsed() + */ function Timer(options) { options = options || {}; const now = options.now || defaultNow; let startTime; + /** + * Starts the timer. + * @function + * @name Timer#start + */ this.start = function() { startTime = now(); }; + /** + * Determines the time since the timer was started. + * @function + * @name Timer#elapsed + * @returns {number} Elapsed time in milliseconds, or NaN if the timer has not been started + */ this.elapsed = function() { return now() - startTime; }; diff --git a/src/core/ParallelReportDispatcher.js b/src/core/ParallelReportDispatcher.js index fc508eb9..84d43461 100644 --- a/src/core/ParallelReportDispatcher.js +++ b/src/core/ParallelReportDispatcher.js @@ -1,13 +1,17 @@ getJasmineRequireObj().ParallelReportDispatcher = function(j$) { - /* - A report dispatcher packaged for convenient use from outside jasmine-core. - - This isn't part of the public interface, but it is used by - jasmine-npm. -core and -npm version in lockstep at the major and minor - levels but version independently at the patch level. Any changes that - would break -npm should be done in a major or minor release, never a - patch release, and accompanied by a change to -npm that's released in - the same version. + /** + * @class ParallelReportDispatcher + * @implements Reporter + * @classdesc A report dispatcher packaged for convenient use from outside jasmine-core. + * + * This is intended to help packages like `jasmine` (the Jasmine runner for + * Node.js) do their own report dispatching in order to support parallel + * execution. If you aren't implementing a runner package that supports + * parallel execution, this class probably isn't what you're looking for. + * + * Warning: Do not use ParallelReportDispatcher in the same process that + * Jasmine specs run in. Doing so will break Jasmine's error handling. + * @param onError {function} Function called when an unhandled exception, unhandled promise rejection, or explicit reporter failure occurs */ function ParallelReportDispatcher(onError, deps = {}) { const ReportDispatcher = deps.ReportDispatcher || j$.ReportDispatcher; @@ -45,9 +49,33 @@ getJasmineRequireObj().ParallelReportDispatcher = function(j$) { ); const self = { + /** + * Adds a reporter to the list of reporters that events will be dispatched to. + * @function + * @name ParallelReportDispatcher#addReporter + * @param {Reporter} reporterToAdd The reporter to be added. + * @see custom_reporter + */ addReporter: dispatcher.addReporter.bind(dispatcher), + /** + * Clears all registered reporters. + * @function + * @name ParallelReportDispatcher#clearReporters + */ clearReporters: dispatcher.clearReporters.bind(dispatcher), + /** + * Installs a global error handler. After this method is called, any + * unhandled exceptions or unhandled promise rejections will be passed to + * the onError callback that was passed to the constructor. + * @function + * @name ParallelReportDispatcher#installGlobalErrors + */ installGlobalErrors: globalErrors.install.bind(globalErrors), + /** + * Uninstalls the global error handler. + * @function + * @name ParallelReportDispatcher#uninstallGlobalErrors + */ uninstallGlobalErrors: function() { // late-bind uninstall because it doesn't exist until install is called globalErrors.uninstall(globalErrors); diff --git a/src/core/QueueRunner.js b/src/core/QueueRunner.js index 65bdc4df..0982c0bd 100644 --- a/src/core/QueueRunner.js +++ b/src/core/QueueRunner.js @@ -1,13 +1,4 @@ getJasmineRequireObj().QueueRunner = function(j$) { - /* - QueueRunner isn't part of the public interface, but it is used by - jasmine-npm. -core and -npm version in lockstep at the major and minor - levels but version independently at the patch level. Any changes that - would break -npm should be done in a major or minor release, never a - patch release, and accompanied by a change to -npm that's released in - the same version. - */ - let nextid = 1; function StopExecutionError() {} diff --git a/src/core/ReportDispatcher.js b/src/core/ReportDispatcher.js index adb09170..55759d03 100644 --- a/src/core/ReportDispatcher.js +++ b/src/core/ReportDispatcher.js @@ -1,13 +1,4 @@ getJasmineRequireObj().ReportDispatcher = function(j$) { - /* - ReportDispatcher isn't part of the public interface, but it is used by - jasmine-npm. -core and -npm version in lockstep at the major and minor - levels but version independently at the patch level. Any changes that - would break -npm should be done in a major or minor release, never a - patch release, and accompanied by a change to -npm that's released in - the same version. - */ - function ReportDispatcher(methods, queueRunnerFactory, onLateError) { const dispatchedMethods = methods || []; diff --git a/src/core/Timer.js b/src/core/Timer.js index 26266313..098345b3 100644 --- a/src/core/Timer.js +++ b/src/core/Timer.js @@ -1,29 +1,39 @@ getJasmineRequireObj().Timer = function() { - /* - Timer isn't part of the public interface, but it is used by - jasmine-npm. -core and -npm version in lockstep at the major and minor - levels but version independently at the patch level. Any changes that - would break -npm should be done in a major or minor release, never a - patch release, and accompanied by a change to -npm that's released in - the same version. - */ - const defaultNow = (function(Date) { return function() { return new Date().getTime(); }; })(Date); + /** + * @class Timer + * @classdesc Tracks elapsed time + * @example + * const timer = new jasmine.Timer(); + * timer.start(); + * const elapsed = timer.elapsed() + */ function Timer(options) { options = options || {}; const now = options.now || defaultNow; let startTime; + /** + * Starts the timer. + * @function + * @name Timer#start + */ this.start = function() { startTime = now(); }; + /** + * Determines the time since the timer was started. + * @function + * @name Timer#elapsed + * @returns {number} Elapsed time in milliseconds, or NaN if the timer has not been started + */ this.elapsed = function() { return now() - startTime; };