From b6426d24146c495282d5701eb70d4a9b79986bbf Mon Sep 17 00:00:00 2001 From: Steve Gravrock Date: Wed, 15 Oct 2025 21:50:56 -0700 Subject: [PATCH] Flesh out jasmine-html.js API reference --- lib/jasmine-core/jasmine-html.js | 32 +++++++++++++++++++++++++++----- src/html/HtmlReporter.js | 2 +- src/html/HtmlReporterV2.js | 10 +++++++++- src/html/HtmlReporterV2Urls.js | 14 ++++++++++++-- src/html/HtmlSpecFilter.js | 6 +++++- 5 files changed, 54 insertions(+), 10 deletions(-) diff --git a/lib/jasmine-core/jasmine-html.js b/lib/jasmine-core/jasmine-html.js index 14ff61a3..4b932657 100644 --- a/lib/jasmine-core/jasmine-html.js +++ b/lib/jasmine-core/jasmine-html.js @@ -53,7 +53,7 @@ jasmineRequire.HtmlReporter = function(j$) { * @implements {Reporter} * @param options Options object. See lib/jasmine-core/boot1.js for details. * @since 1.2.0 - * @deprecated + * @deprecated Use {@link HtmlReporterV2} instead. */ class HtmlReporter { #env; @@ -263,6 +263,11 @@ jasmineRequire.HtmlReporter = function(j$) { jasmineRequire.HtmlSpecFilter = function(j$) { 'use strict'; + /** + * @class HtmlSpecFilter + * @param options Options object. See lib/jasmine-core/boot1.js for details. + * @deprecated Use {@link HtmlReporterV2Urls} instead. + */ function HtmlSpecFilter(options) { j$.getEnv().deprecated( 'HtmlReporter and HtmlSpecFilter are deprecated. Use HtmlReporterV2 instead.' @@ -280,7 +285,6 @@ jasmineRequire.HtmlSpecFilter = function(j$) { * @function * @param {string} specName The full name of the spec * @returns {boolean} - * @deprcated */ this.matches = function(specName) { return filterPattern.test(specName); @@ -998,8 +1002,16 @@ jasmineRequire.HtmlReporterV2 = function(j$) { * @class HtmlReporterV2 * @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. + * @param options Options object * @since 6.0.0 + * @example + * const env = jasmine.getEnv(); + * const urls = new jasmine.HtmlReporterV2Urls(); + * const reporter = new jasmine.HtmlReporterV2({ + * env, + * urls, + * container: document.body + * }); */ class HtmlReporterV2 { #env; @@ -1249,7 +1261,11 @@ jasmineRequire.HtmlReporterV2Urls = function(j$) { 'use strict'; // TODO unify with V2 UrlBuilder? - // TODO jsdoc + /** + * @class HtmlReporterV2Urls + * @classdesc Processes URLs for {@link HtmlReporterV2}. + * @since 6.0.0 + */ class HtmlReporterV2Urls { constructor(options = {}) { // queryString is injectable for use in our own tests, but user code will @@ -1263,7 +1279,13 @@ jasmineRequire.HtmlReporterV2Urls = function(j$) { }); } - // TODO jsdoc. This is public. + /** + * Creates a {@link Configuration} from the current page's URL. + * @returns {Configuration} + * @example + * const urls = new jasmine.HtmlReporterV2Urls(); + * env.configure(urls.configFromCurrentUrl()); + */ configFromCurrentUrl() { const config = { stopOnSpecFailure: this.queryString.getParam('stopOnSpecFailure'), diff --git a/src/html/HtmlReporter.js b/src/html/HtmlReporter.js index ff875425..019e5bab 100644 --- a/src/html/HtmlReporter.js +++ b/src/html/HtmlReporter.js @@ -9,7 +9,7 @@ jasmineRequire.HtmlReporter = function(j$) { * @implements {Reporter} * @param options Options object. See lib/jasmine-core/boot1.js for details. * @since 1.2.0 - * @deprecated + * @deprecated Use {@link HtmlReporterV2} instead. */ class HtmlReporter { #env; diff --git a/src/html/HtmlReporterV2.js b/src/html/HtmlReporterV2.js index 327770f1..c06b4413 100644 --- a/src/html/HtmlReporterV2.js +++ b/src/html/HtmlReporterV2.js @@ -7,8 +7,16 @@ jasmineRequire.HtmlReporterV2 = function(j$) { * @class HtmlReporterV2 * @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. + * @param options Options object * @since 6.0.0 + * @example + * const env = jasmine.getEnv(); + * const urls = new jasmine.HtmlReporterV2Urls(); + * const reporter = new jasmine.HtmlReporterV2({ + * env, + * urls, + * container: document.body + * }); */ class HtmlReporterV2 { #env; diff --git a/src/html/HtmlReporterV2Urls.js b/src/html/HtmlReporterV2Urls.js index ac307099..bb48b47f 100644 --- a/src/html/HtmlReporterV2Urls.js +++ b/src/html/HtmlReporterV2Urls.js @@ -2,7 +2,11 @@ jasmineRequire.HtmlReporterV2Urls = function(j$) { 'use strict'; // TODO unify with V2 UrlBuilder? - // TODO jsdoc + /** + * @class HtmlReporterV2Urls + * @classdesc Processes URLs for {@link HtmlReporterV2}. + * @since 6.0.0 + */ class HtmlReporterV2Urls { constructor(options = {}) { // queryString is injectable for use in our own tests, but user code will @@ -16,7 +20,13 @@ jasmineRequire.HtmlReporterV2Urls = function(j$) { }); } - // TODO jsdoc. This is public. + /** + * Creates a {@link Configuration} from the current page's URL. + * @returns {Configuration} + * @example + * const urls = new jasmine.HtmlReporterV2Urls(); + * env.configure(urls.configFromCurrentUrl()); + */ configFromCurrentUrl() { const config = { stopOnSpecFailure: this.queryString.getParam('stopOnSpecFailure'), diff --git a/src/html/HtmlSpecFilter.js b/src/html/HtmlSpecFilter.js index ee21e15f..e86cfee9 100644 --- a/src/html/HtmlSpecFilter.js +++ b/src/html/HtmlSpecFilter.js @@ -1,6 +1,11 @@ jasmineRequire.HtmlSpecFilter = function(j$) { 'use strict'; + /** + * @class HtmlSpecFilter + * @param options Options object. See lib/jasmine-core/boot1.js for details. + * @deprecated Use {@link HtmlReporterV2Urls} instead. + */ function HtmlSpecFilter(options) { j$.getEnv().deprecated( 'HtmlReporter and HtmlSpecFilter are deprecated. Use HtmlReporterV2 instead.' @@ -18,7 +23,6 @@ jasmineRequire.HtmlSpecFilter = function(j$) { * @function * @param {string} specName The full name of the spec * @returns {boolean} - * @deprcated */ this.matches = function(specName) { return filterPattern.test(specName);