diff --git a/lib/jasmine-core/jasmine.js b/lib/jasmine-core/jasmine.js index b4909f79..29b550eb 100644 --- a/lib/jasmine-core/jasmine.js +++ b/lib/jasmine-core/jasmine.js @@ -679,11 +679,21 @@ getJasmineRequireObj().util = function(j$) { }; getJasmineRequireObj().Spec = function(j$) { + /** + * @interface Spec + * @see Configuration#specFilter + */ function Spec(attrs) { this.expectationFactory = attrs.expectationFactory; this.asyncExpectationFactory = attrs.asyncExpectationFactory; this.resultCallback = attrs.resultCallback || function() {}; this.id = attrs.id; + /** + * The description passed to the {@link it} that created this spec. + * @name Spec#description + * @readonly + * @type {string} + */ this.description = attrs.description || ''; this.queueableFn = attrs.queueableFn; this.beforeAndAfterFns = @@ -875,6 +885,12 @@ getJasmineRequireObj().Spec = function(j$) { return 'passed'; }; + /** + * The full description including all ancestors of this spec. + * @name Spec#getFullName + * @function + * @returns {string} + */ Spec.prototype.getFullName = function() { return this.getSpecName(this); }; @@ -1046,12 +1062,19 @@ getJasmineRequireObj().Env = function(j$) { * @default false */ oneFailurePerSpec: false, + /** + * A function that takes a spec and returns true if it should be executed + * or false if it should be skipped. + * @callback SpecFilter + * @param {Spec} spec - The spec that the filter is being applied to. + * @return boolean + */ /** * Function to use to filter specs * @name Configuration#specFilter * @since 3.3.0 - * @type function - * @default true + * @type SpecFilter + * @default A function that always returns true. */ specFilter: function() { return true; @@ -1681,7 +1704,27 @@ getJasmineRequireObj().Env = function(j$) { queueRunnerFactory ); - // Both params are optional. + /** + * Executes the specs. + * + * If called with no parameters or with a falsy value as the first parameter, + * all specs will be executed except those that are excluded by a + * [spec filter]{@link Configuration#specFilter} or other mechanism. If the + * first parameter is a list of spec/suite IDs, only those specs/suites will + * be run. + * + * Both parameters are optional, but a completion callback is only valid as + * the second parameter. To specify a completion callback but not a list of + * specs/suites to run, pass null or undefined as the first parameter. + * + * execute should not be called more than once. + * + * @name Env#execute + * @since 2.0.0 + * @function + * @param {(string[])=} runnablesToRun IDs of suites and/or specs to run + * @param {Function=} onComplete Function that will be called after all specs have run + */ this.execute = function(runnablesToRun, onComplete) { installGlobalErrors(); @@ -1873,6 +1916,15 @@ getJasmineRequireObj().Env = function(j$) { } }); + /** + * Configures whether Jasmine should allow the same function to be spied on + * more than once during the execution of a spec. By default, spying on + * a function that is already a spy will cause an error. + * @name Env#allowRespy + * @function + * @since 2.5.0 + * @param {boolean} allow Whether to allow respying + */ this.allowRespy = function(allow) { spyRegistry.allowRespy(allow); }; diff --git a/src/core/Env.js b/src/core/Env.js index 2c1f4cf8..ab3c3405 100644 --- a/src/core/Env.js +++ b/src/core/Env.js @@ -83,12 +83,19 @@ getJasmineRequireObj().Env = function(j$) { * @default false */ oneFailurePerSpec: false, + /** + * A function that takes a spec and returns true if it should be executed + * or false if it should be skipped. + * @callback SpecFilter + * @param {Spec} spec - The spec that the filter is being applied to. + * @return boolean + */ /** * Function to use to filter specs * @name Configuration#specFilter * @since 3.3.0 - * @type function - * @default true + * @type SpecFilter + * @default A function that always returns true. */ specFilter: function() { return true; @@ -718,7 +725,27 @@ getJasmineRequireObj().Env = function(j$) { queueRunnerFactory ); - // Both params are optional. + /** + * Executes the specs. + * + * If called with no parameters or with a falsy value as the first parameter, + * all specs will be executed except those that are excluded by a + * [spec filter]{@link Configuration#specFilter} or other mechanism. If the + * first parameter is a list of spec/suite IDs, only those specs/suites will + * be run. + * + * Both parameters are optional, but a completion callback is only valid as + * the second parameter. To specify a completion callback but not a list of + * specs/suites to run, pass null or undefined as the first parameter. + * + * execute should not be called more than once. + * + * @name Env#execute + * @since 2.0.0 + * @function + * @param {(string[])=} runnablesToRun IDs of suites and/or specs to run + * @param {Function=} onComplete Function that will be called after all specs have run + */ this.execute = function(runnablesToRun, onComplete) { installGlobalErrors(); @@ -910,6 +937,15 @@ getJasmineRequireObj().Env = function(j$) { } }); + /** + * Configures whether Jasmine should allow the same function to be spied on + * more than once during the execution of a spec. By default, spying on + * a function that is already a spy will cause an error. + * @name Env#allowRespy + * @function + * @since 2.5.0 + * @param {boolean} allow Whether to allow respying + */ this.allowRespy = function(allow) { spyRegistry.allowRespy(allow); }; diff --git a/src/core/Spec.js b/src/core/Spec.js index 83d389d4..81d244dd 100644 --- a/src/core/Spec.js +++ b/src/core/Spec.js @@ -1,9 +1,19 @@ getJasmineRequireObj().Spec = function(j$) { + /** + * @interface Spec + * @see Configuration#specFilter + */ function Spec(attrs) { this.expectationFactory = attrs.expectationFactory; this.asyncExpectationFactory = attrs.asyncExpectationFactory; this.resultCallback = attrs.resultCallback || function() {}; this.id = attrs.id; + /** + * The description passed to the {@link it} that created this spec. + * @name Spec#description + * @readonly + * @type {string} + */ this.description = attrs.description || ''; this.queueableFn = attrs.queueableFn; this.beforeAndAfterFns = @@ -195,6 +205,12 @@ getJasmineRequireObj().Spec = function(j$) { return 'passed'; }; + /** + * The full description including all ancestors of this spec. + * @name Spec#getFullName + * @function + * @returns {string} + */ Spec.prototype.getFullName = function() { return this.getSpecName(this); };