Add a first pass at jsdoc.

[##130415655] #596

src/core/CallTracker.js

@@ -1,5 +1,8 @@
 getJasmineRequireObj().CallTracker = function(j$) {
 
+  /**
+   * @namespace Spy#calls
+   */
   function CallTracker() {
     var calls = [];
     var opts = {};
@@ -24,23 +27,54 @@ getJasmineRequireObj().CallTracker = function(j$) {
       calls.push(context);
     };
 
+    /**
+     * Check whether this spy has been invoked.
+     * @name Spy#calls#any
+     * @function
+     * @return {Boolean}
+     */
     this.any = function() {
       return !!calls.length;
     };
 
+    /**
+     * Get the number of invocations of this spy.
+     * @name Spy#calls#count
+     * @function
+     * @return {Integer}
+     */
     this.count = function() {
       return calls.length;
     };
 
+    /**
+     * Get the arguments that were passed to a specific invocation of this spy.
+     * @name Spy#calls#argsFor
+     * @function
+     * @param {Integer} index The 0-based invocation index.
+     * @return {Array}
+     */
     this.argsFor = function(index) {
       var call = calls[index];
       return call ? call.args : [];
     };
 
+    /**
+     * Get the raw calls array for this spy.
+     * @name Spy#calls#all
+     * @function
+     * @return {Spy.callData[]}
+     */
     this.all = function() {
       return calls;
     };
 
+    /**
+     * Get all of the arguments for each invocation of this spy in the order they were received.
+     * @name Spy#calls#allArgs
+     * @function
+     * @return {Array}
+     */
     this.allArgs = function() {
       var callArgs = [];
       for(var i = 0; i < calls.length; i++){
@@ -50,18 +84,40 @@ getJasmineRequireObj().CallTracker = function(j$) {
       return callArgs;
     };
 
+    /**
+     * Get the first invocation of this spy.
+     * @name Spy#calls#first
+     * @function
+     * @return {ObjecSpy.callData}
+     */
     this.first = function() {
       return calls[0];
     };
 
+    /**
+     * Get the most recent invocation of this spy.
+     * @name Spy#calls#mostRecent
+     * @function
+     * @return {ObjecSpy.callData}
+     */
     this.mostRecent = function() {
       return calls[calls.length - 1];
     };
 
+    /**
+     * Reset this spy as if it has never been called.
+     * @name Spy#calls#reset
+     * @function
+     */
     this.reset = function() {
       calls = [];
     };
 
+    /**
+     * Set this spy to do a shallow clone of arguments passed to each invocation.
+     * @name Spy#calls#saveArgumentsByValue
+     * @function
+     */
     this.saveArgumentsByValue = function() {
       opts.cloneArgs = true;
     };

src/core/Clock.js

@@ -1,4 +1,9 @@
 getJasmineRequireObj().Clock = function() {
+  /**
+   * _Note:_ Do not construct this directly, Jasmine will make one during booting. You can get the current clock with {@link jasmine.clock}.
+   * @class Clock
+   * @classdesc Jasmine's mock clock is used when testing time dependent code.
+   */
   function Clock(global, delayedFunctionSchedulerFactory, mockDate) {
     var self = this,
       realTimingFunctions = {
@@ -18,6 +23,12 @@ getJasmineRequireObj().Clock = function() {
       timer;
 
 
+    /**
+     * Install the mock clock over the built-in methods.
+     * @name Clock#install
+     * @function
+     * @return {Clock}
+     */
     self.install = function() {
       if(!originalTimingFunctionsIntact()) {
         throw new Error('Jasmine Clock was unable to install over custom global timer functions. Is the clock already installed?');
@@ -30,6 +41,11 @@ getJasmineRequireObj().Clock = function() {
       return self;
     };
 
+    /**
+     * Uninstall the mock clock, returning the built-in methods to their places.
+     * @name Clock#uninstall
+     * @function
+     */
     self.uninstall = function() {
       delayedFunctionScheduler = null;
       mockDate.uninstall();
@@ -39,6 +55,14 @@ getJasmineRequireObj().Clock = function() {
       installed = false;
     };
 
+    /**
+     * Execute a function with a mocked Clock
+     *
+     * The clock will be {@link Clock#install|install}ed before the function is called and {@link Clock#uninstall|uninstall}ed in a `finally` after the function completes.
+     * @name Clock#withMock
+     * @function
+     * @param {closure} Function The function to be called.
+     */
     self.withMock = function(closure) {
       this.install();
       try {
@@ -48,6 +72,12 @@ getJasmineRequireObj().Clock = function() {
       }
     };
 
+    /**
+     * Instruct the installed Clock to also mock the date returned by `new Date()`
+     * @name Clock#mockDate
+     * @function
+     * @param {Date} [initialDate=now] The `Date` to provide.
+     */
     self.mockDate = function(initialDate) {
       mockDate.install(initialDate);
     };
@@ -80,6 +110,12 @@ getJasmineRequireObj().Clock = function() {
       return Function.prototype.call.apply(timer.clearInterval, [global, id]);
     };
 
+    /**
+     * Tick the Clock forward, running any enqueued timeouts along the way
+     * @name Clock#tick
+     * @function
+     * @param {int} millis The number of milliseconds to tick.
+     */
     self.tick = function(millis) {
       if (installed) {
         delayedFunctionScheduler.tick(millis, function(millis) { mockDate.tick(millis); });

src/core/Env.js

@@ -1,4 +1,10 @@
 getJasmineRequireObj().Env = function(j$) {
+  /**
+   * _Note:_ Do not construct this directly, Jasmine will make one during booting.
+   * @name Env
+   * @classdesc The Jasmine environment
+   * @constructor
+   */
   function Env(options) {
     options = options || {};
 
@@ -266,6 +272,11 @@ getJasmineRequireObj().Env = function(j$) {
       });
     };
 
+    /**
+     * @name Env#addReporter
+     * @function
+     * @tutorial addReporter
+     */
     this.addReporter = function(reporterToAdd) {
       reporter.addReporter(reporterToAdd);
     };

src/core/Expectation.js

@@ -1,5 +1,9 @@
 getJasmineRequireObj().Expectation = function() {
 
+  /**
+   * Matchers that come with Jasmine out of the box.
+   * @namespace matchers
+   */
   function Expectation(options) {
     this.util = options.util || { buildFailureMessage: function() {} };
     this.customEqualityTesters = options.customEqualityTesters || [];

src/core/JsApiReporter.js

@@ -5,6 +5,13 @@ getJasmineRequireObj().JsApiReporter = function() {
     elapsed: function(){ return 0; }
   };
 
+  /**
+   * _Note:_ Do not construct this directly, use the global `jsApiReporter` to retrieve the instantiated object.
+   *
+   * @name jsApiReporter
+   * @classdesc Reporter added by default in `boot.js` to record results for retrieval in javascript code.
+   * @class
+   */
   function JsApiReporter(options) {
     var timer = options.timer || noopTimer,
         status = 'loaded';
@@ -28,6 +35,10 @@ getJasmineRequireObj().JsApiReporter = function() {
       status = 'done';
     };
 
+    /**
+     * @name jsApiReporter#status
+     * @function
+     */
     this.status = function() {
       return status;
     };
@@ -43,6 +54,10 @@ getJasmineRequireObj().JsApiReporter = function() {
       storeSuite(result);
     };
 
+    /**
+     * @name jsApiReporter#suiteResults
+     * @function
+     */
     this.suiteResults = function(index, length) {
       return suites.slice(index, index + length);
     };

src/core/Spy.js

@@ -8,6 +8,11 @@ getJasmineRequireObj().Spy = function (j$) {
     };
   })();
 
+  /**
+   * _Note:_ Do not construct this directly, use {@link spyOn}, {@link spyOnProperty}, {@link jasmine.createSpy}, or {@link jasmine.createSpyObj}
+   * @constructor
+   * @name Spy
+   */
   function Spy(name, originalFn) {
     var args = buildArgs(),
       /*`eval` is the only option to preserve both this and context:
@@ -27,6 +32,12 @@ getJasmineRequireObj().Spy = function (j$) {
       }),
       callTracker = new j$.CallTracker(),
       spy = function () {
+        /**
+         * @name Spy.callData
+         * @property {object} object - `this` context for the invocation.
+         * @property {number} invocationOrder - Order of the invocation.
+         * @property {Array} args - The arguments passed for this invocation.
+         */
         var callData = {
           object: this,
           invocationOrder: nextOrder(),

src/core/SpyStrategy.js

@@ -1,5 +1,8 @@
 getJasmineRequireObj().SpyStrategy = function(j$) {
 
+  /**
+   * @namespace Spy#and
+   */
   function SpyStrategy(options) {
     options = options || {};
 
@@ -8,19 +11,41 @@ getJasmineRequireObj().SpyStrategy = function(j$) {
         getSpy = options.getSpy || function() {},
         plan = function() {};
 
+    /**
+     * Return the identifying information for the spy.
+     * @name Spy#and#identity
+     * @function
+     * @returns {String}
+     */
     this.identity = function() {
       return identity;
     };
 
+    /**
+     * Execute the current spy strategy.
+     * @name Spy#and#exec
+     * @function
+     */
     this.exec = function() {
       return plan.apply(this, arguments);
     };
 
+    /**
+     * Tell the spy to call through to the real implementation when invoked.
+     * @name Spy#and#callThrough
+     * @function
+     */
     this.callThrough = function() {
       plan = originalFn;
       return getSpy();
     };
 
+    /**
+     * Tell the spy to return the value when invoked.
+     * @name Spy#and#returnValue
+     * @function
+     * @param {*} value The value to return.
+     */
     this.returnValue = function(value) {
       plan = function() {
         return value;
@@ -28,6 +53,12 @@ getJasmineRequireObj().SpyStrategy = function(j$) {
       return getSpy();
     };
 
+    /**
+     * Tell the spy to return one of the specified values (sequentially) each time the spy is invoked.
+     * @name Spy#and#returnValues
+     * @function
+     * @param {...*} values - Values to be returned on subsequent calls to the spy.
+     */
     this.returnValues = function() {
       var values = Array.prototype.slice.call(arguments);
       plan = function () {
@@ -36,6 +67,12 @@ getJasmineRequireObj().SpyStrategy = function(j$) {
       return getSpy();
     };
 
+    /**
+     * Tell the spy to throw an error when invoked.
+     * @name Spy#and#throwError
+     * @function
+     * @param {Error|String} something Thing to throw
+     */
     this.throwError = function(something) {
       var error = (something instanceof Error) ? something : new Error(something);
       plan = function() {
@@ -44,6 +81,12 @@ getJasmineRequireObj().SpyStrategy = function(j$) {
       return getSpy();
     };
 
+    /**
+     * Tell the spy to call a fake implementation when invoked.
+     * @name Spy#and#callFake
+     * @function
+     * @param {Function} fn The function to invoke with the passed parameters.
+     */
     this.callFake = function(fn) {
       if(!j$.isFunction_(fn)) {
         throw new Error('Argument passed to callFake should be a function, got ' + fn);
@@ -52,6 +95,11 @@ getJasmineRequireObj().SpyStrategy = function(j$) {
       return getSpy();
     };
 
+    /**
+     * Tell the spy to do nothing when invoked. This is the default.
+     * @name Spy#and#stub
+     * @function
+     */
     this.stub = function(fn) {
       plan = function() {};
       return getSpy();

src/core/base.js

@@ -3,14 +3,30 @@ getJasmineRequireObj().base = function(j$, jasmineGlobal) {
     throw new Error('unimplemented method');
   };
 
+  /**
+   * @name jasmine.MAX_PRETTY_PRINT_DEPTH
+   */
   j$.MAX_PRETTY_PRINT_DEPTH = 40;
+  /**
+   * @name jasmine.MAX_PRETTY_PRINT_ARRAY_LENGTH
+   */
   j$.MAX_PRETTY_PRINT_ARRAY_LENGTH = 100;
+  /**
+   * @name jasmine.DEFAULT_TIMEOUT_INTERVAL
+   */
   j$.DEFAULT_TIMEOUT_INTERVAL = 5000;
 
   j$.getGlobal = function() {
     return jasmineGlobal;
   };
 
+  /**
+   * Get the currently booted Jasmine Environment.
+   *
+   * @name jasmine.getEnv
+   * @function
+   * @return {Env}
+   */
   j$.getEnv = function(options) {
     var env = j$.currentEnv_ = j$.currentEnv_ || new j$.Env(options);
     //jasmine. singletons in here (setTimeout blah blah).
@@ -58,26 +74,51 @@ getJasmineRequireObj().base = function(j$, jasmineGlobal) {
     return matches ? matches[1] : '<anonymous>';
   };
 
+  /**
+   * @name jasmine.any
+   * @function
+   */
   j$.any = function(clazz) {
     return new j$.Any(clazz);
   };
 
+  /**
+   * @name jasmine.anything
+   * @function
+   */
   j$.anything = function() {
     return new j$.Anything();
   };
 
+  /**
+   * @name jasmine.objectContaining
+   * @function
+   */
   j$.objectContaining = function(sample) {
     return new j$.ObjectContaining(sample);
   };
 
+  /**
+   * @name jasmine.stringMatching
+   * @function
+   */
   j$.stringMatching = function(expected) {
     return new j$.StringMatching(expected);
   };
 
+  /**
+   * @name jasmine.arrayContaining
+   * @function
+   */
   j$.arrayContaining = function(sample) {
     return new j$.ArrayContaining(sample);
   };
 
+  /**
+   * @name jasmine.createSpy
+   * @function
+   * @return {Spy}
+   */
   j$.createSpy = function(name, originalFn) {
     return j$.Spy(name, originalFn);
   };
@@ -90,6 +131,10 @@ getJasmineRequireObj().base = function(j$, jasmineGlobal) {
       putativeSpy.calls instanceof j$.CallTracker;
   };
 
+  /**
+   * @name jasmine.createSpyObj
+   * @function
+   */
   j$.createSpyObj = function(baseName, methodNames) {
     var baseNameIsCollection = j$.isObject_(baseName) || j$.isArray_(baseName);
 

src/core/matchers/toBe.js

@@ -1,4 +1,12 @@
 getJasmineRequireObj().toBe = function() {
+  /**
+   * {@link expect} the actual value to be `===` to the expected value.
+   * @function
+   * @name matchers#toBe
+   * @param {Object} expected - The expected value to compare against.
+   * @example
+   * expect(thing).toBe(realThing);
+   */
   function toBe() {
     return {
       compare: function(actual, expected) {

src/core/matchers/toBeCloseTo.js

@@ -1,5 +1,13 @@
 getJasmineRequireObj().toBeCloseTo = function() {
-
+  /**
+   * {@link expect} the actual value to be within a specified precision of the expected value.
+   * @function
+   * @name matchers#toBeCloseTo
+   * @param {Object} expected - The expected value to compare against.
+   * @param {Number} [precision=2] - The number of decimal points to check.
+   * @example
+   * expect(number).toBeCloseTo(42.2, 3);
+   */
   function toBeCloseTo() {
     return {
       compare: function(actual, expected, precision) {

src/core/matchers/toBeDefined.js

@@ -1,4 +1,11 @@
 getJasmineRequireObj().toBeDefined = function() {
+  /**
+   * {@link expect} the actual value to be defined. (Not `undefined`)
+   * @function
+   * @name matchers#toBeDefined
+   * @example
+   * expect(result).toBeDefined();
+   */
   function toBeDefined() {
     return {
       compare: function(actual) {

src/core/matchers/toBeFalsy.js

@@ -1,4 +1,11 @@
 getJasmineRequireObj().toBeFalsy = function() {
+  /**
+   * {@link expect} the actual value to be falsy
+   * @function
+   * @name matchers#toBeFalsy
+   * @example
+   * expect(result).toBeFalsy();
+   */
   function toBeFalsy() {
     return {
       compare: function(actual) {

src/core/matchers/toBeGreaterThan.js

@@ -1,5 +1,12 @@
 getJasmineRequireObj().toBeGreaterThan = function() {
-
+  /**
+   * {@link expect} the actual value to be greater than the expected value.
+   * @function
+   * @name matchers#toBeGreaterThan
+   * @param {Number} expected - The value to compare against.
+   * @example
+   * expect(result).toBeGreaterThan(3);
+   */
   function toBeGreaterThan() {
     return {
       compare: function(actual, expected) {

src/core/matchers/toBeGreaterThanOrEqual.js

@@ -1,5 +1,12 @@
 getJasmineRequireObj().toBeGreaterThanOrEqual = function() {
-
+  /**
+   * {@link expect} the actual value to be greater than or equal to the expected value.
+   * @function
+   * @name matchers#toBeGreaterThanOrEqual
+   * @param {Number} expected - The expected value to compare against.
+   * @example
+   * expect(result).toBeGreaterThanOrEqual(25);
+   */
   function toBeGreaterThanOrEqual() {
     return {
       compare: function(actual, expected) {

src/core/matchers/toBeLessThan.js

@@ -1,4 +1,12 @@
 getJasmineRequireObj().toBeLessThan = function() {
+  /**
+   * {@link expect} the actual value to be less than the expected value.
+   * @function
+   * @name matchers#toBeLessThan
+   * @param {Number} expected - The expected value to compare against.
+   * @example
+   * expect(result).toBeLessThan(0);
+   */
   function toBeLessThan() {
     return {
 
@@ -11,4 +19,4 @@ getJasmineRequireObj().toBeLessThan = function() {
   }
 
   return toBeLessThan;
-};
+};

src/core/matchers/toBeLessThanOrEqual.js

@@ -1,4 +1,12 @@
 getJasmineRequireObj().toBeLessThanOrEqual = function() {
+  /**
+   * {@link expect} the actual value to be less than or equal to the expected value.
+   * @function
+   * @name matchers#toBeLessThanOrEqual
+   * @param {Number} expected - The expected value to compare against.
+   * @example
+   * expect(result).toBeLessThanOrEqual(123);
+   */
   function toBeLessThanOrEqual() {
     return {
 

src/core/matchers/toBeNaN.js

@@ -1,5 +1,11 @@
 getJasmineRequireObj().toBeNaN = function(j$) {
-
+  /**
+   * {@link expect} the actual value to be `NaN` (Not a Number).
+   * @function
+   * @name matchers#toBeNaN
+   * @example
+   * expect(thing).toBeNaN();
+   */
   function toBeNaN() {
     return {
       compare: function(actual) {

src/core/matchers/toBeNull.js

@@ -1,5 +1,11 @@
 getJasmineRequireObj().toBeNull = function() {
-
+  /**
+   * {@link expect} the actual value to be `null`.
+   * @function
+   * @name matchers#toBeNull
+   * @example
+   * expect(result).toBeNull();
+   */
   function toBeNull() {
     return {
       compare: function(actual) {

src/core/matchers/toBeTruthy.js

@@ -1,5 +1,11 @@
 getJasmineRequireObj().toBeTruthy = function() {
-
+  /**
+   * {@link expect} the actual value to be truthy.
+   * @function
+   * @name matchers#toBeTruthy
+   * @example
+   * expect(thing).toBeTruthy();
+   */
   function toBeTruthy() {
     return {
       compare: function(actual) {

src/core/matchers/toBeUndefined.js

@@ -1,5 +1,11 @@
 getJasmineRequireObj().toBeUndefined = function() {
-
+  /**
+   * {@link expect} the actual value to be `undefined`.
+   * @function
+   * @name matchers#toBeUndefined
+   * @example
+   * expect(result).toBeUndefined():
+   */
   function toBeUndefined() {
     return {
       compare: function(actual) {

src/core/matchers/toContain.js

@@ -1,4 +1,13 @@
 getJasmineRequireObj().toContain = function() {
+  /**
+   * {@link expect} the actual value to contain a specific value.
+   * @function
+   * @name matchers#toContain
+   * @param {Object} expected - The value to look for.
+   * @example
+   * expect(array).toContain(anElement);
+   * expect(string).toContain(substring);
+   */
   function toContain(util, customEqualityTesters) {
     customEqualityTesters = customEqualityTesters || [];
 

src/core/matchers/toEqual.js

@@ -1,5 +1,12 @@
 getJasmineRequireObj().toEqual = function(j$) {
-
+  /**
+   * {@link expect} the actual value to be equal to the expected, using deep equality comparison.
+   * @function
+   * @name matchers#toEqual
+   * @param {Object} expected - Expected value
+   * @example
+   * expect(bigObject).toEqual({"foo": ['bar', 'baz']});
+   */
   function toEqual(util, customEqualityTesters) {
     customEqualityTesters = customEqualityTesters || [];
 

src/core/matchers/toHaveBeenCalled.js

@@ -2,6 +2,14 @@ getJasmineRequireObj().toHaveBeenCalled = function(j$) {
 
   var getErrorMsg = j$.formatErrorMsg('<toHaveBeenCalled>', 'expect(<spyObj>).toHaveBeenCalled()');
 
+  /**
+   * {@link expect} the actual (a {@link Spy}) to have been called.
+   * @function
+   * @name matchers#toHaveBeenCalled
+   * @example
+   * expect(mySpy).toHaveBeenCalled();
+   * expect(mySpy).not.toHaveBeenCalled();
+   */
   function toHaveBeenCalled() {
     return {
       compare: function(actual) {

src/core/matchers/toHaveBeenCalledBefore.js

@@ -2,6 +2,14 @@ getJasmineRequireObj().toHaveBeenCalledBefore = function(j$) {
 
   var getErrorMsg = j$.formatErrorMsg('<toHaveBeenCalledBefore>', 'expect(<spyObj>).toHaveBeenCalledBefore(<spyObj>)');
 
+  /**
+   * {@link expect} the actual value (a {@link Spy}) to have been called before another {@link Spy}.
+   * @function
+   * @name matchers#toHaveBeenCalledBefore
+   * @param {Spy} expected - {@link Spy} that should have been called after the `actual` {@link Spy}.
+   * @example
+   * expect(mySpy).toHaveBeenCalledBefore(otherSpy);
+   */
   function toHaveBeenCalledBefore() {
     return {
       compare: function(firstSpy, latterSpy) {

src/core/matchers/toHaveBeenCalledTimes.js

@@ -2,6 +2,14 @@ getJasmineRequireObj().toHaveBeenCalledTimes = function(j$) {
 
   var getErrorMsg = j$.formatErrorMsg('<toHaveBeenCalledTimes>', 'expect(<spyObj>).toHaveBeenCalledTimes(<Number>)');
 
+  /**
+   * {@link expect} the actual (a {@link Spy}) to have been called the specified number of times.
+   * @function
+   * @name matchers#toHaveBeenCalledTimes
+   * @param {Number} expected - The number of invocations to look for.
+   * @example
+   * expect(mySpy).toHaveBeenCalledTimes(3);
+   */
   function toHaveBeenCalledTimes() {
     return {
       compare: function(actual, expected) {

src/core/matchers/toHaveBeenCalledWith.js

@@ -2,6 +2,14 @@ getJasmineRequireObj().toHaveBeenCalledWith = function(j$) {
 
   var getErrorMsg = j$.formatErrorMsg('<toHaveBeenCalledWith>', 'expect(<spyObj>).toHaveBeenCalledWith(...arguments)');
 
+  /**
+   * {@link expect} the actual (a {@link Spy}) to have been called with particular arguments at least once.
+   * @function
+   * @name matchers#toHaveBeenCalledWith
+   * @param {...Object} - The arguments to look for
+   * @example
+   * expect(mySpy).toHaveBeenCalledWith('foo', 'bar', 2);
+   */
   function toHaveBeenCalledWith(util, customEqualityTesters) {
     return {
       compare: function() {

src/core/matchers/toMatch.js

@@ -2,6 +2,15 @@ getJasmineRequireObj().toMatch = function(j$) {
 
   var getErrorMsg = j$.formatErrorMsg('<toMatch>', 'expect(<expectation>).toMatch(<string> || <regexp>)');
 
+  /**
+   * {@link expect} the actual value to match a regular expression
+   * @function
+   * @name matchers#toMatch
+   * @param {RegExp|String} expected - Value to look for in the string.
+   * @example
+   * expect("my string").toMatch(/string$/);
+   * expect("other string").toMatch("her");
+   */
   function toMatch() {
     return {
       compare: function(actual, expected) {

src/core/matchers/toThrow.js

@@ -2,6 +2,15 @@ getJasmineRequireObj().toThrow = function(j$) {
 
   var getErrorMsg = j$.formatErrorMsg('<toThrow>', 'expect(function() {<expectation>}).toThrow()');
 
+  /**
+   * {@link expect} a function to `throw` something.
+   * @function
+   * @name matchers#toThrow
+   * @param {Object} [expected] - Value that should be thrown. If not provided, simply the fact that something was thrown will be checked.
+   * @example
+   * expect(function() { return 'things'; }).toThrow('foo');
+   * expect(function() { return 'stuff'; }).toThrow();
+   */
   function toThrow(util) {
     return {
       compare: function(actual, expected) {

src/core/matchers/toThrowError.js

@@ -2,6 +2,19 @@ getJasmineRequireObj().toThrowError = function(j$) {
 
   var getErrorMsg =  j$.formatErrorMsg('<toThrowError>', 'expect(function() {<expectation>}).toThrowError(<ErrorConstructor>, <message>)');
 
+  /**
+   * {@link expect} a function to `throw` an `Error`.
+   * @function
+   * @name matchers#toThrowError
+   * @param {Error} [expected] - `Error` constructor the object that was thrown needs to be an instance of. If not provided, `Error` will be used.
+   * @param {RegExp|String} [message] - The message that should be set on the thrown `Error`
+   * @example
+   * expect(function() { return 'things'; }).toThrowError(MyCustomError, 'message');
+   * expect(function() { return 'things'; }).toThrowError(MyCustomError, /bar/);
+   * expect(function() { return 'stuff'; }).toThrowError(MyCustomError);
+   * expect(function() { return 'other'; }).toThrowError(/foo/);
+   * expect(function() { return 'other'; }).toThrowError();
+   */
   function toThrowError () {
     return {
       compare: function(actual) {

src/core/requireInterface.js

@@ -1,61 +1,198 @@
 getJasmineRequireObj().interface = function(jasmine, env) {
   var jasmineInterface = {
+    /**
+     * Create a suite of specs
+     *
+     * @name describe
+     * @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
+     */
     describe: function(description, specDefinitions) {
       return env.describe(description, specDefinitions);
     },
 
+    /**
+     * A temporarily disabled [`describe`]{@link describe}
+     *
+     * Specs within an `xdescribe` will be marked pending and not executed
+     * @name xdescribe
+     * @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
+     */
     xdescribe: function(description, specDefinitions) {
       return env.xdescribe(description, specDefinitions);
     },
 
+    /**
+     * A focused [`describe`]{@link describe}
+     *
+     * If suites or specs are focused, only those that are focused will be executed
+     * @see {fit}
+     * @name fdescribe
+     * @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
+     */
     fdescribe: function(description, specDefinitions) {
       return env.fdescribe(description, specDefinitions);
     },
 
+    /**
+     * A single spec
+     * @name it
+     * @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 {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async spec.
+     */
     it: function() {
       return env.it.apply(env, arguments);
     },
 
+    /**
+     * A temporarily disabled [`it`]{@link it}
+     *
+     * The spec will report as `pending` and will not be executed.
+     * @name xit
+     * @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.
+     */
     xit: function() {
       return env.xit.apply(env, arguments);
     },
 
+    /**
+     * A focused [`it`]{@link it}
+     *
+     * If suites or specs are focused, only those that are focused will be executed.
+     * @name fit
+     * @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 {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async spec.
+     */
     fit: function() {
       return env.fit.apply(env, arguments);
     },
 
+    /**
+     * Run some shared setup before each of the specs in the {@link describe} in which it is called.
+     * @name beforeEach
+     * @function
+     * @global
+     * @param {Function} [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() {
       return env.beforeEach.apply(env, arguments);
     },
 
+    /**
+     * Run some shared teardown after each of the specs in the {@link describe} in which it is called.
+     * @name afterEach
+     * @function
+     * @global
+     * @param {Function} [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() {
       return env.afterEach.apply(env, arguments);
     },
 
+    /**
+     * Run some shared setup once before all of the specs in the {@link describe} are run.
+     *
+     * _Note:_ Be careful, sharing the setup from a beforeAll makes it easy to accidentally leak state between your specs so that they erroneously pass or fail.
+     * @name beforeAll
+     * @function
+     * @global
+     * @param {Function} [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() {
       return env.beforeAll.apply(env, arguments);
     },
 
+    /**
+     * Run some shared teardown once before 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 {Int} [timeout={@link jasmine.DEFAULT_TIMEOUT_INTERVAL}] Custom timeout for an async afterAll.
+     */
     afterAll: function() {
       return env.afterAll.apply(env, arguments);
     },
 
+    /**
+     * Create an expectation for a spec.
+     * @name expect
+     * @function
+     * @global
+     * @param {Object} actual - Actual computed value to test expectations against.
+     * @return {matchers}
+     */
     expect: function(actual) {
       return env.expect(actual);
     },
 
+    /**
+     * Mark a spec as pending, expectation results will be ignored.
+     * @name pending
+     * @function
+     * @global
+     * @param {String} [message] - Reason the spec is pending.
+     */
     pending: function() {
       return env.pending.apply(env, arguments);
     },
 
+    /**
+     * Explicitly mark a spec as failed.
+     * @name fail
+     * @function
+     * @global
+     * @param {String|Error} [error] - Reason for the failure.
+    */
     fail: function() {
       return env.fail.apply(env, arguments);
     },
 
+    /**
+     * Install a spy onto an existing object.
+     * @name spyOn
+     * @function
+     * @global
+     * @param {Object} obj - The object upon which to install the {@link Spy}.
+     * @param {String} methodName - The name of the method to replace with a {@link Spy}.
+     * @returns {Spy}
+     */
     spyOn: function(obj, methodName) {
       return env.spyOn(obj, methodName);
     },
 
+    /**
+     * Install a spy on a property onto an existing object.
+     * @name spyOnProperty
+     * @function
+     * @global
+     * @param {Object} obj - The object upon which to install the {@link Spy}
+     * @param {String} propertyName - The name of the property to replace with a {@link Spy}.
+     * @param {String} [accessType=get] - The access type (get|set) of the property to {@link Spy} on.
+     * @returns {Spy}
+     */
     spyOnProperty: function(obj, methodName, accessType) {
       return env.spyOnProperty(obj, methodName, accessType);
     },
@@ -64,17 +201,35 @@ getJasmineRequireObj().interface = function(jasmine, env) {
       timer: new jasmine.Timer()
     }),
 
+    /**
+     * @namespace jasmine
+     */
     jasmine: jasmine
   };
 
+  /**
+   * @name jasmine.addCustomEqualityTester
+   * @function
+   * @tutorial addCustomEqualityTester
+   */
   jasmine.addCustomEqualityTester = function(tester) {
     env.addCustomEqualityTester(tester);
   };
 
+  /**
+   * @name jasmine.addMatchers
+   * @function
+   * @tutorial addMatchers
+   */
   jasmine.addMatchers = function(matchers) {
     return env.addMatchers(matchers);
   };
 
+  /**
+   * @name jasmine.clock
+   * @function
+   * @returns {Clock}
+   */
   jasmine.clock = function() {
     return env.clock;
   };