Add a first pass at jsdoc.

[##130415655] #596

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) {