From 80dba1138a0ec2e860e4fb4d8fac765ef2747ab6 Mon Sep 17 00:00:00 2001 From: Gregg Van Hove Date: Tue, 8 Aug 2017 17:28:36 -0700 Subject: [PATCH] Add explicit docs for the callback function passed to `it` etc. --- lib/jasmine-core/jasmine.js | 44 ++++++++++++++++++++++++------------ src/core/requireInterface.js | 30 ++++++++++++++++-------- 2 files changed, 49 insertions(+), 25 deletions(-) diff --git a/lib/jasmine-core/jasmine.js b/lib/jasmine-core/jasmine.js index a2af4239..d2e1ae34 100644 --- a/lib/jasmine-core/jasmine.js +++ b/lib/jasmine-core/jasmine.js @@ -2599,15 +2599,19 @@ getJasmineRequireObj().matchersUtil = function(j$) { // Recursively compare objects and arrays. // Compare array lengths to determine if a deep comparison is necessary. if (className == '[object Array]') { - size = a.length; - if (size !== b.length) { - diffBuilder.record(a, b); - return false; - } + var aLength = a.length; + var bLength = b.length; - for (i = 0; i < size; i++) { + diffBuilder.withPath('length', function() { + if (aLength !== bLength) { + diffBuilder.record(aLength, bLength); + result = false; + } + }); + + for (i = 0; i < aLength || i < bLength; i++) { diffBuilder.withPath(i, function() { - result = eq(a[i], b[i], aStack, bStack, customTesters, diffBuilder) && result; + result = eq(i < aLength ? a[i] : void 0, i < bLength ? b[i] : void 0, aStack, bStack, customTesters, diffBuilder) && result; }); } if (!result) { @@ -4274,6 +4278,16 @@ getJasmineRequireObj().ReportDispatcher = function() { getJasmineRequireObj().interface = function(jasmine, env) { var jasmineInterface = { + /** + * Callback passed to parts of the Jasmine base interface. + * + * By default Jasmine assumes this function completes synchronously. + * If you have code that you need to test asynchronously, you can declare that you receive a `done` callback, return a Promise, or use the `async` keyword if it is supported in your environment. + * @callback implementationCallback + * @param {Function} done Used to specify to Jasmine that this callback is asynchronous and Jasmine should wait until it has been called before moving on. + * @returns {} Optionally return a Promise instead of using `done` to cause Jasmine to wait for completion. + */ + /** * Create a group of specs (often called a suite). * @@ -4325,7 +4339,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @function * @global * @param {String} description Textual description of what this spec is checking - * @param {Function} [testFunction] Function that contains the code of your test. If not provided the test will be `pending`. + * @param {implementationCallback} [testFunction] Function that contains the code of your test. If not provided the test will be `pending`. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async spec. */ it: function() { @@ -4340,7 +4354,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @function * @global * @param {String} description Textual description of what this spec is checking. - * @param {Function} [testFunction] Function that contains the code of your test. Will not be executed. + * @param {implementationCallback} [testFunction] Function that contains the code of your test. Will not be executed. */ xit: function() { return env.xit.apply(env, arguments); @@ -4354,7 +4368,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @function * @global * @param {String} description Textual description of what this spec is checking. - * @param {Function} testFunction Function that contains the code of your test. + * @param {implementationCallback} testFunction Function that contains the code of your test. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async spec. */ fit: function() { @@ -4366,7 +4380,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @name beforeEach * @function * @global - * @param {Function} [function] Function that contains the code to setup your specs. + * @param {implementationCallback} [function] Function that contains the code to setup your specs. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async beforeEach. */ beforeEach: function() { @@ -4378,7 +4392,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @name afterEach * @function * @global - * @param {Function} [function] Function that contains the code to teardown your specs. + * @param {implementationCallback} [function] Function that contains the code to teardown your specs. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async afterEach. */ afterEach: function() { @@ -4392,7 +4406,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @name beforeAll * @function * @global - * @param {Function} [function] Function that contains the code to setup your specs. + * @param {implementationCallback} [function] Function that contains the code to setup your specs. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async beforeAll. */ beforeAll: function() { @@ -4400,13 +4414,13 @@ getJasmineRequireObj().interface = function(jasmine, env) { }, /** - * Run some shared teardown once before all of the specs in the {@link describe} are run. + * Run some shared teardown once after all of the specs in the {@link describe} are run. * * _Note:_ Be careful, sharing the teardown from a afterAll makes it easy to accidentally leak state between your specs so that they erroneously pass or fail. * @name afterAll * @function * @global - * @param {Function} [function] Function that contains the code to teardown your specs. + * @param {implementationCallback} [function] Function that contains the code to teardown your specs. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async afterAll. */ afterAll: function() { diff --git a/src/core/requireInterface.js b/src/core/requireInterface.js index 9becb320..ad4ed013 100644 --- a/src/core/requireInterface.js +++ b/src/core/requireInterface.js @@ -1,5 +1,15 @@ getJasmineRequireObj().interface = function(jasmine, env) { var jasmineInterface = { + /** + * Callback passed to parts of the Jasmine base interface. + * + * By default Jasmine assumes this function completes synchronously. + * If you have code that you need to test asynchronously, you can declare that you receive a `done` callback, return a Promise, or use the `async` keyword if it is supported in your environment. + * @callback implementationCallback + * @param {Function} [done] Used to specify to Jasmine that this callback is asynchronous and Jasmine should wait until it has been called before moving on. + * @returns {} Optionally return a Promise instead of using `done` to cause Jasmine to wait for completion. + */ + /** * Create a group of specs (often called a suite). * @@ -8,7 +18,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @function * @global * @param {String} description Textual description of the group - * @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites a specs + * @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites and specs */ describe: function(description, specDefinitions) { return env.describe(description, specDefinitions); @@ -22,7 +32,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @function * @global * @param {String} description Textual description of the group - * @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites a specs + * @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites and specs */ xdescribe: function(description, specDefinitions) { return env.xdescribe(description, specDefinitions); @@ -37,7 +47,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @function * @global * @param {String} description Textual description of the group - * @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites a specs + * @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites and specs */ fdescribe: function(description, specDefinitions) { return env.fdescribe(description, specDefinitions); @@ -51,7 +61,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @function * @global * @param {String} description Textual description of what this spec is checking - * @param {Function} [testFunction] Function that contains the code of your test. If not provided the test will be `pending`. + * @param {implementationCallback} [testFunction] Function that contains the code of your test. If not provided the test will be `pending`. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async spec. */ it: function() { @@ -66,7 +76,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @function * @global * @param {String} description Textual description of what this spec is checking. - * @param {Function} [testFunction] Function that contains the code of your test. Will not be executed. + * @param {implementationCallback} [testFunction] Function that contains the code of your test. Will not be executed. */ xit: function() { return env.xit.apply(env, arguments); @@ -80,7 +90,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @function * @global * @param {String} description Textual description of what this spec is checking. - * @param {Function} testFunction Function that contains the code of your test. + * @param {implementationCallback} testFunction Function that contains the code of your test. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async spec. */ fit: function() { @@ -92,7 +102,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @name beforeEach * @function * @global - * @param {Function} [function] Function that contains the code to setup your specs. + * @param {implementationCallback} [function] Function that contains the code to setup your specs. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async beforeEach. */ beforeEach: function() { @@ -104,7 +114,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @name afterEach * @function * @global - * @param {Function} [function] Function that contains the code to teardown your specs. + * @param {implementationCallback} [function] Function that contains the code to teardown your specs. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async afterEach. */ afterEach: function() { @@ -118,7 +128,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @name beforeAll * @function * @global - * @param {Function} [function] Function that contains the code to setup your specs. + * @param {implementationCallback} [function] Function that contains the code to setup your specs. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async beforeAll. */ beforeAll: function() { @@ -132,7 +142,7 @@ getJasmineRequireObj().interface = function(jasmine, env) { * @name afterAll * @function * @global - * @param {Function} [function] Function that contains the code to teardown your specs. + * @param {implementationCallback} [function] Function that contains the code to teardown your specs. * @param {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async afterAll. */ afterAll: function() {