From fa481b2bd157a295cdc65490ed5bf250ca70e9b6 Mon Sep 17 00:00:00 2001 From: Steve Gravrock Date: Wed, 17 Sep 2025 07:30:34 -0700 Subject: [PATCH] API reference docs for HTML reporter and spec filters --- lib/jasmine-core/jasmine-html.js | 45 ++++++++++++++++++++++++++++++++ src/html/HtmlExactSpecFilter.js | 17 ++++++++++++ src/html/HtmlReporter.js | 12 +++++++++ src/html/HtmlSpecFilter.js | 16 ++++++++++++ 4 files changed, 90 insertions(+) diff --git a/lib/jasmine-core/jasmine-html.js b/lib/jasmine-core/jasmine-html.js index 7de406bf..93b10583 100644 --- a/lib/jasmine-core/jasmine-html.js +++ b/lib/jasmine-core/jasmine-html.js @@ -84,6 +84,13 @@ jasmineRequire.HtmlReporter = function(j$) { } }; + /** + * @class HtmlReporter + * @classdesc Displays results and allows re-running individual specs and suites. + * @implements {Reporter} + * @param options Options object. See lib/jasmine-core/boot1.js for details. + * @since 1.2.0 + */ function HtmlReporter(options) { function config() { return (options.env && options.env.configuration()) || {}; @@ -101,6 +108,11 @@ jasmineRequire.HtmlReporter = function(j$) { const deprecationWarnings = []; const failures = []; + /** + * Initializes the reporter. Should be called before {@link Env#execute}. + * @function + * @name HtmlReporter#initialize + */ this.initialize = function() { clearPrior(); htmlReporterMain = createDom( @@ -891,6 +903,15 @@ jasmineRequire.HtmlReporter = function(j$) { }; jasmineRequire.HtmlSpecFilter = function() { + /** + * @name HtmlSpecFilter + * @classdesc Legacy HTML spec filter, for backward compatibility + * with boot files that predate {@link HtmlExactSpecFilter}. + * @param options Object with a filterString method + * @constructor + * @deprecated + * @since 1.2.0 + */ // Legacy HTML spec filter, preserved for backward compatibility with // boot files that predate HtmlExactSpecFilterV2 function HtmlSpecFilter(options) { @@ -905,6 +926,13 @@ jasmineRequire.HtmlSpecFilter = function() { const filterPattern = new RegExp(filterString); + /** + * Determines whether the spec with the specified name should be executed. + * @name HtmlSpecFilter#matches + * @function + * @param {string} specName The full name of the spec + * @returns {boolean} + */ this.matches = function(specName) { return filterPattern.test(specName); }; @@ -993,9 +1021,21 @@ jasmineRequire.QueryString = function() { }; jasmineRequire.HtmlExactSpecFilter = function() { + /** + * Spec filter for use with {@link HtmlReporter} + * + * See lib/jasmine-core/boot1.js for usage. + * @since 5.11.0 + */ class HtmlExactSpecFilter { #getFilterString; + /** + * Create a filter instance. + * @param options Object with a filterString method, which should + * return the value of the "spec" query string parameter set by + * {@link HtmlReporter}. + */ constructor(options) { if (typeof options?.filterString !== 'function') { throw new Error('options.filterString must be a function'); @@ -1004,6 +1044,11 @@ jasmineRequire.HtmlExactSpecFilter = function() { this.#getFilterString = options.filterString; } + /** + * Determines whether the specified spec should be executed. + * @param {Spec} spec + * @returns {boolean} + */ matches(spec) { const filterString = this.#getFilterString(); diff --git a/src/html/HtmlExactSpecFilter.js b/src/html/HtmlExactSpecFilter.js index 01c32ae0..f4209c7c 100644 --- a/src/html/HtmlExactSpecFilter.js +++ b/src/html/HtmlExactSpecFilter.js @@ -1,7 +1,19 @@ jasmineRequire.HtmlExactSpecFilter = function() { + /** + * Spec filter for use with {@link HtmlReporter} + * + * See lib/jasmine-core/boot1.js for usage. + * @since 5.11.0 + */ class HtmlExactSpecFilter { #getFilterString; + /** + * Create a filter instance. + * @param options Object with a filterString method, which should + * return the value of the "spec" query string parameter set by + * {@link HtmlReporter}. + */ constructor(options) { if (typeof options?.filterString !== 'function') { throw new Error('options.filterString must be a function'); @@ -10,6 +22,11 @@ jasmineRequire.HtmlExactSpecFilter = function() { this.#getFilterString = options.filterString; } + /** + * Determines whether the specified spec should be executed. + * @param {Spec} spec + * @returns {boolean} + */ matches(spec) { const filterString = this.#getFilterString(); diff --git a/src/html/HtmlReporter.js b/src/html/HtmlReporter.js index ff3ee80d..ed011091 100644 --- a/src/html/HtmlReporter.js +++ b/src/html/HtmlReporter.js @@ -49,6 +49,13 @@ jasmineRequire.HtmlReporter = function(j$) { } }; + /** + * @class HtmlReporter + * @classdesc Displays results and allows re-running individual specs and suites. + * @implements {Reporter} + * @param options Options object. See lib/jasmine-core/boot1.js for details. + * @since 1.2.0 + */ function HtmlReporter(options) { function config() { return (options.env && options.env.configuration()) || {}; @@ -66,6 +73,11 @@ jasmineRequire.HtmlReporter = function(j$) { const deprecationWarnings = []; const failures = []; + /** + * Initializes the reporter. Should be called before {@link Env#execute}. + * @function + * @name HtmlReporter#initialize + */ this.initialize = function() { clearPrior(); htmlReporterMain = createDom( diff --git a/src/html/HtmlSpecFilter.js b/src/html/HtmlSpecFilter.js index 320d2f61..187b20f2 100644 --- a/src/html/HtmlSpecFilter.js +++ b/src/html/HtmlSpecFilter.js @@ -1,4 +1,13 @@ jasmineRequire.HtmlSpecFilter = function() { + /** + * @name HtmlSpecFilter + * @classdesc Legacy HTML spec filter, for backward compatibility + * with boot files that predate {@link HtmlExactSpecFilter}. + * @param options Object with a filterString method + * @constructor + * @deprecated + * @since 1.2.0 + */ // Legacy HTML spec filter, preserved for backward compatibility with // boot files that predate HtmlExactSpecFilterV2 function HtmlSpecFilter(options) { @@ -13,6 +22,13 @@ jasmineRequire.HtmlSpecFilter = function() { const filterPattern = new RegExp(filterString); + /** + * Determines whether the spec with the specified name should be executed. + * @name HtmlSpecFilter#matches + * @function + * @param {string} specName The full name of the spec + * @returns {boolean} + */ this.matches = function(specName) { return filterPattern.test(specName); };