dwf: more doc commits

README.markdown

@@ -67,8 +67,6 @@ Jasmine has several built-in matchers.  Here are a few:
 
 `toBeFalsy()` returns true if the object or primitive evaluates to false
 
-`wasNotCalledWith()` returns true if the object is a spy and was called with the passed arguments
-
 `toContain()` returns true if an array or string contains the passed variable.
 
 `toNotContain()` returns true if an array or string does not contain the passed variable.
@@ -164,13 +162,13 @@ timeout before the next block is run. You supply a time to wait before the next
     });
 
     runs(function () {
-      this.expects_that(this.foo).should_equal(0);
+      this.expects(this.foo).toEqual(0);
     });
 
     waits(500);
 
     runs(function () {
-      this.expects_that(this.foo).should_equal(1);
+      this.expects(this.foo).toEqual(1);
     });
 	});
 
@@ -252,7 +250,7 @@ Similarly, there is an afterEach declaration.  It takes a function that is run a
     });
 
 ### Nested Describes
-Jasmine now supports nested describes. An example: 
+Jasmine supports nested describes. An example:
 
     describe('some suite', function () {
 

lib/jasmine.js

@@ -1,14 +1,25 @@
-/*
- * Jasmine internal classes & objects
+/**
+ * Top level namespace for Jasmine, a lightweight JavaScript BDD/spec/testing framework.
+ * 
+ * @namespace
  */
-
-/** @namespace */
 var jasmine = {};
 
+/**
+ * @private
+ */
 jasmine.unimplementedMethod_ = function() {
   throw new Error("unimplemented method");
 };
 
+/**
+ * Allows for bound functions to be comapred.  Internal use only.
+ *
+ * @ignore
+ * @private
+ * @param base {Object} bound 'this' for the function
+ * @param name {Function} function to find
+ */
 jasmine.bindOriginal_ = function(base, name) {
   var original = base[name];
   return function() {
@@ -35,10 +46,19 @@ jasmine.ExpectationResult = function(passed, message, details) {
   this.trace = new Error(message); // todo: test better
 };
 
+/**
+ * Getter for the Jasmine environment. Ensures one gets created
+ */
 jasmine.getEnv = function() {
   return jasmine.currentEnv_ = jasmine.currentEnv_ || new jasmine.Env();
 };
 
+/**
+ * @ignore
+ * @private
+ * @param value
+ * @returns {Boolean}
+ */
 jasmine.isArray_ = function(value) {
   return value &&
   typeof value === 'object' &&
@@ -47,70 +67,249 @@ jasmine.isArray_ = function(value) {
   !(value.propertyIsEnumerable('length'));
 };
 
+/**
+ * Pretty printer for expecations.  Takes any object and turns it into a human-readable string.
+ *
+ * @param value {Object} an object to be outputted
+ * @returns {String}
+ */
 jasmine.pp = function(value) {
   var stringPrettyPrinter = new jasmine.StringPrettyPrinter();
   stringPrettyPrinter.format(value);
   return stringPrettyPrinter.string;
 };
 
+/**
+ * Returns true if the object is a DOM Node.
+ *
+ * @param {Object} obj object to check
+ * @returns {Boolean}
+ */
 jasmine.isDomNode = function(obj) {
   return obj['nodeType'] > 0;
 };
 
+/**
+ * Returns a matchable 'generic' object of the class type.  For use in expecations of type when values don't matter.
+ *
+ * @example
+ * // don't care about which function is passed in, as long as it's a function
+ * expect(mySpy).wasCalledWith(jasmine.any(Function));
+ *
+ * @param {Class} clazz
+ * @returns matchable object of the type clazz
+ */
 jasmine.any = function(clazz) {
   return new jasmine.Matchers.Any(clazz);
 };
 
+/**
+ * Jasmine Spies are test doubles that can act as stubs, spies, fakes or when used in an expecation, mocks.
+ *
+ * Spies should be created in test setup, before expectations.  They can then be checked, using the standard Jasmine
+ * expectation syntax. Spies can be checked if they were called or not and what the calling params were.
+ *
+ * A Spy has the following mehtod: wasCalled, callCount, mostRecentCall, and argsForCall (see docs)
+ * Spies are torn down at the end of every spec.
+ *
+ * Note: Do <b>not</b> call new jasmine.Spy() directly - a spy must be created using spyOn, jasmine.createSpy or jasmine.createSpyObj.
+ * 
+ * @example
+ * // a stub
+ * var myStub = jasmine.createSpy('myStub');  // can be used anywhere
+ *
+ * // spy example
+ * var foo = {
+ *   not: function(bool) { return !bool; }
+ * }
+ *
+ * // actual foo.not will not be called, execution stops
+ * spyOn(foo, 'not');
+
+ // foo.not spied upon, execution will continue to implementation
+ * spyOn(foo, 'not').andCallThrough();
+ *
+ * // fake example
+ * var foo = {
+ *   not: function(bool) { return !bool; }
+ * }
+ *
+ * // foo.not(val) will return val
+ * spyOn(foo, 'not').andCallFake(function(value) {return value;});
+ *
+ * // mock example
+ * foo.not(7 == 7);
+ * expect(foo.not).wasCalled();
+ * expect(foo.not).wasCalledWith(true);
+ *
+ * @constructor
+ * @see spyOn, jasmine.createSpy, jasmine.createSpyObj
+ * @param {String} name
+ */
+jasmine.Spy = function(name) {
+  /**
+   * The name of the spy, if provided.
+   */
+  this.identity = name || 'unknown';
+  /**
+   *  Is this Object a spy?
+   */
+  this.isSpy = true;
+  /**
+   * The acutal function this spy stubs.
+   */
+  this.plan = function() {};
+  /**
+   * Tracking of the most recent call to the spy.
+   * @example
+   * var mySpy = jasmine.createSpy('foo');
+   * mySpy(1, 2);
+   * mySpy.mostRecentCall.args = [1, 2];
+   */
+  this.mostRecentCall = {};
+
+  /**
+   * Holds arguments for each call to the spy, indexed by call count
+   * @example
+   * var mySpy = jasmine.createSpy('foo');
+   * mySpy(1, 2);
+   * mySpy(7, 8);
+   * mySpy.mostRecentCall.args = [7, 8];
+   * mySpy.argsForCall[0] = [1, 2];
+   * mySpy.argsForCall[1] = [7, 8];
+   */
+  this.argsForCall = [];
+};
+
+/**
+ * Tells a spy to call through to the actual implemenatation.
+ *
+ * @example
+ * var foo = {
+ *   bar: function() { // do some stuff }
+ * }
+ * 
+ * // defining a spy on an existing property: foo.bar
+ * spyOn(foo, 'bar').andCallThrough();
+ */
+jasmine.Spy.prototype.andCallThrough = function() {
+  this.plan = this.originalValue;
+  return this;
+};
+
+/**
+ * For setting the return value of a spy.
+ *
+ * @example
+ * // defining a spy from scratch: foo() returns 'baz'
+ * var foo = jasmine.createSpy('spy on foo').andReturn('baz');
+ *
+ * // defining a spy on an existing property: foo.bar() returns 'baz'
+ * spyOn(foo, 'bar').andReturn('baz');
+ *
+ * @param {Object} value
+ */
+jasmine.Spy.prototype.andReturn = function(value) {
+  this.plan = function() {
+    return value;
+  };
+  return this;
+};
+
+/**
+ * For throwing an exception when a spy is called.
+ *
+ * @example
+ * // defining a spy from scratch: foo() throws an exception w/ message 'ouch'
+ * var foo = jasmine.createSpy('spy on foo').andThrow('baz');
+ *
+ * // defining a spy on an existing property: foo.bar() throws an exception w/ message 'ouch'
+ * spyOn(foo, 'bar').andThrow('baz');
+ *
+ * @param {String} exceptionMsg
+ */
+jasmine.Spy.prototype.andThrow = function(exceptionMsg) {
+  this.plan = function() {
+    throw exceptionMsg;
+  };
+  return this;
+};
+
+/**
+ * Calls an alternate implementation when a spy is called.
+ *
+ * @example
+ * var baz = function() {
+ *   // do some stuff, return something
+ * }
+ * // defining a spy from scratch: foo() calls the function baz
+ * var foo = jasmine.createSpy('spy on foo').andCall(baz);
+ *
+ * // defining a spy on an existing property: foo.bar() calls an anonymnous function
+ * spyOn(foo, 'bar').andCall(function() { return 'baz';} );
+ *
+ * @param {Function} fakeFunc
+ */
+jasmine.Spy.prototype.andCallFake = function(fakeFunc) {
+  this.plan = fakeFunc;
+  return this;
+};
+
+/**
+ * Resets all of a spy's the tracking variables so that it can be used again.
+ *
+ * @example
+ * spyOn(foo, 'bar');
+ *
+ * foo.bar();
+ *
+ * expect(foo.bar.callCount).toEqual(1);
+ *
+ * foo.bar.reset();
+ *
+ * expect(foo.bar.callCount).toEqual(0);
+ */
+jasmine.Spy.prototype.reset = function() {
+  this.wasCalled = false;
+  this.callCount = 0;
+  this.argsForCall = [];
+  this.mostRecentCall = {};
+};
+
 jasmine.createSpy = function(name) {
+
   var spyObj = function() {
     spyObj.wasCalled = true;
     spyObj.callCount++;
     var args = jasmine.util.argsToArray(arguments);
-    spyObj.mostRecentCall = {
-      object: this,
-      args: args
-    };
+    //spyObj.mostRecentCall = {
+    //  object: this,
+    //  args: args
+    //};
+    spyObj.mostRecentCall.object = this;
+    spyObj.mostRecentCall.args = args;
     spyObj.argsForCall.push(args);
     return spyObj.plan.apply(this, arguments);
   };
 
-  spyObj.identity = name || 'unknown';
-  spyObj.isSpy = true;
+  var spy = new jasmine.Spy(name);
   
-  spyObj.plan = function() {
-  };
+  for(var prop in spy) {
+    spyObj[prop] = spy[prop];
+  }
   
-  spyObj.andCallThrough = function() {
-    spyObj.plan = spyObj.originalValue;
-    return spyObj;
-  };
-  spyObj.andReturn = function(value) {
-    spyObj.plan = function() {
-      return value;
-    };
-    return spyObj;
-  };
-  spyObj.andThrow = function(exceptionMsg) {
-    spyObj.plan = function() {
-      throw exceptionMsg;
-    };
-    return spyObj;
-  };
-  spyObj.andCallFake = function(fakeFunc) {
-    spyObj.plan = fakeFunc;
-    return spyObj;
-  };
-  spyObj.reset = function() {
-    spyObj.wasCalled = false;
-    spyObj.callCount = 0;
-    spyObj.argsForCall = [];
-    spyObj.mostRecentCall = {};
-  };
   spyObj.reset();
 
   return spyObj;
 };
 
+/**
+ * Creates a more complicated spy: an Object that has every property a function that is a spy.  Used for stubbing something
+ * large in one call.
+ *
+ * @param {String} baseName name of spy class
+ * @param {Array} methodNames array of names of methods to make spies
+ */
 jasmine.createSpyObj = function(baseName, methodNames) {
   var obj = {};
   for (var i = 0; i < methodNames.length; i++) {
@@ -123,50 +322,146 @@ jasmine.log = function(message) {
   jasmine.getEnv().currentSpec.getResults().log(message);
 };
 
+/**
+ * Function that installs a spy on an existing object's method name.  Used within a Spec to create a spy.
+ *
+ * @example
+ * // spy example
+ * var foo = {
+ *   not: function(bool) { return !bool; }
+ * }
+ * spyOn(foo, 'not'); // actual foo.not will not be called, execution stops
+ *
+ * @see jasmine.createSpy
+ * @param obj
+ * @param methodName
+ * @returns a Jasmine spy that can be chained with all spy methods
+ */
 var spyOn = function(obj, methodName) {
   return jasmine.getEnv().currentSpec.spyOn(obj, methodName);
 };
 
+/**
+ * Creates a Jasmine spec that will be added to the current suite.
+ *
+ * // TODO: pending tests
+ *
+ * @example
+ * it('should be true', function() {
+ *   expect(true).toEqual(true);
+ * });
+ *
+ * @param {String} desc description of this specification
+ * @param {Function} func defines the preconditions and expectations of the spec
+ */
 var it = function(desc, func) {
   return jasmine.getEnv().it(desc, func);
 };
 
+/**
+ * Creates a <em>disabled</em> Jasmine spec.
+ *
+ * A convenience method that allows existing specs to be disabled temporarily during development.
+ *
+ * @param {String} desc description of this specification
+ * @param {Function} func defines the preconditions and expectations of the spec
+ */
 var xit = function(desc, func) {
   return jasmine.getEnv().xit(desc, func);
 };
 
+/**
+ * Starts a chain for a Jasmine expectation.
+ *
+ * It is passed an Object that is the actual value and should chain to one of the many
+ * jasmine.Matchers functions.
+ *
+ * @param {Object} actual Actual value to test against and expected value
+ */
 var expect = function(actual) {
   return jasmine.getEnv().currentSpec.expect(actual);
 };
 
+/**
+ * Defines part of a jasmine spec.  Used in cominbination with waits or waitsFor in asynchrnous specs.
+ *
+ * @param {Function} func Function that defines part of a jasmine spec.
+ */
 var runs = function(func) {
   jasmine.getEnv().currentSpec.runs(func);
 };
 
+/**
+ * Waits for a timeout before moving to the next runs()-defined block.
+ * @param {Number} timeout
+ */
 var waits = function(timeout) {
   jasmine.getEnv().currentSpec.waits(timeout);
 };
 
+/**
+ * Waits for the latchFunction to return true before proceeding to the next runs()-defined block.
+ *  
+ * @param {Number} timeout
+ * @param {Function} latchFunction
+ * @param {String} message
+ */
 var waitsFor = function(timeout, latchFunction, message) {
   jasmine.getEnv().currentSpec.waitsFor(timeout, latchFunction, message);
 };
 
+/**
+ * A function that is called before each spec in a suite.
+ *
+ * Used for spec setup, including validating assumptions.
+ *
+ * @param {Function} beforeEachFunction
+ */
 var beforeEach = function(beforeEachFunction) {
   jasmine.getEnv().beforeEach(beforeEachFunction);
 };
 
+/**
+ * A function that is called after each spec in a suite.
+ *
+ * Used for restoring any state that is hijacked during spec execution.
+ *
+ * @param {Function} afterEachFunction
+ */
 var afterEach = function(afterEachFunction) {
   jasmine.getEnv().afterEach(afterEachFunction);
 };
 
+/**
+ * Defines a suite of specifications.
+ *
+ * Stores the description and all defined specs in the Jasmine environment as one suite of specs. Variables declared
+ * are accessible by calls to beforeEach, it, and afterEach. Describe blocks can be nested, allowing for specialization
+ * of setup in some tests.
+ *
+ * @example
+ * // TODO: a simple suite
+ *
+ * // TODO: a simple suite with a nested describe block
+ *
+ * @param {String} description A string, usually the class under test.
+ * @param {Function} specDefinitions function that defines several specs.
+ */
 var describe = function(description, specDefinitions) {
   return jasmine.getEnv().describe(description, specDefinitions);
 };
 
+/**
+ * Disables a suite of specifications.  Used to disable some suites in a file, or files, temporarily during development.
+ *
+ * @param {String} description A string, usually the class under test.
+ * @param {Function} specDefinitions function that defines several specs.
+ */
 var xdescribe = function(description, specDefinitions) {
   return jasmine.getEnv().xdescribe(description, specDefinitions);
 };
 
+
 jasmine.XmlHttpRequest = XMLHttpRequest;
 
 // Provide the XMLHttpRequest class for IE 5.x-6.x:
@@ -190,6 +485,13 @@ if (typeof XMLHttpRequest == "undefined") jasmine.XmlHttpRequest = function() {
   throw new Error("This browser does not support XMLHttpRequest.");
 };
 
+/**
+ * Adds suite files to an HTML document so that they are executed, thus adding them to the current
+ * Jasmine environment.
+ *
+ * @param {String} url path to the file to include
+ * @param {Boolean} opt_global
+ */
 jasmine.include = function(url, opt_global) {
   if (opt_global) {
     document.write('<script type="text/javascript" src="' + url + '"></' + 'script>');
@@ -206,9 +508,18 @@ jasmine.include = function(url, opt_global) {
     return eval(xhr.responseText);
   }
 };
-/** @namespace */
+/**
+ * @namespace
+ */
 jasmine.util = {};
 
+/**
+ * Declare that a child class inherite it's prototype from the parent class.
+ *
+ * @private
+ * @param {Function} childClass
+ * @param {Function} parentClass
+ */
 jasmine.util.inherit = function(childClass, parentClass) {
   var subclass = function() {
   };
@@ -256,11 +567,6 @@ jasmine.util.argsToArray = function(args) {
   return arrayOfArgs;
 };
 
-/**
- * Env
- *
- * @constructor
- */
 jasmine.Env = function() {
   this.currentSpec = null;
   this.currentSuite = null;
@@ -447,6 +753,9 @@ jasmine.ActionCollection = function(env) {
   this.finished = false;
 };
 
+/**
+ * Marks the collection as done & calls the finish callback, if there is one
+ */
 jasmine.ActionCollection.prototype.finish = function() {
   if (this.finishCallback) {
     this.finishCallback();
@@ -454,16 +763,25 @@ jasmine.ActionCollection.prototype.finish = function() {
   this.finished = true;
 };
 
+/**
+ * Starts executing the queue of functions/actions.
+ */
 jasmine.ActionCollection.prototype.execute = function() {
   if (this.actions.length > 0) {
     this.next();
   }
 };
 
+/**
+ * Gets the current action.
+ */
 jasmine.ActionCollection.prototype.getCurrentAction = function() {
   return this.actions[this.index];
 };
 
+/**
+ * Executes the next queued function/action. If there are no more in the queue, calls #finish.
+ */
 jasmine.ActionCollection.prototype.next = function() {
   if (this.index >= this.actions.length) {
     this.finish();
@@ -512,11 +830,6 @@ jasmine.ActionCollection.prototype.waitForDone = function(action) {
     }
   }, 150);
 };
-/*
- * jasmine.Matchers methods; add your own by extending jasmine.Matchers.prototype - don't forget to write a test
- *
- */
-
 jasmine.Matchers = function(env, actual, results) {
   this.env = env;
   this.actual = actual;
@@ -537,17 +850,31 @@ jasmine.Matchers.prototype.report = function(result, failing_message, details) {
   return result;
 };
 
+/**
+ * Matcher that compares the actual to the expected using ===.
+ *
+ * @param expected
+ */
 jasmine.Matchers.prototype.toBe = function(expected) {
   return this.report(this.actual === expected, 'Expected<br /><br />' + jasmine.Matchers.pp(expected)
     + '<br /><br />to be the same object as<br /><br />' + jasmine.Matchers.pp(this.actual)
     + '<br />');
 };
 
+/**
+ * Matcher that compares the actual to the expected using !==
+ * @param expected
+ */
 jasmine.Matchers.prototype.toNotBe = function(expected) {
   return this.report(this.actual !== expected, 'Expected<br /><br />' + jasmine.Matchers.pp(expected)
     + '<br /><br />to be a different object from actual, but they were the same.');
 };
 
+/**
+ * Matcher that compares the actual to the expected using common sense equality. Handles Objects, Arrays, etc.
+ *
+ * @param expected
+ */
 jasmine.Matchers.prototype.toEqual = function(expected) {
   var mismatchKeys = [];
   var mismatchValues = [];
@@ -573,6 +900,10 @@ jasmine.Matchers.prototype.toEqual = function(expected) {
 /** @deprecated */
 jasmine.Matchers.prototype.should_equal = jasmine.Matchers.prototype.toEqual;
 
+/**
+ * Matcher that compares the actual to the expected using the ! of jasmine.Matchers.toEqual
+ * @param expected
+ */
 jasmine.Matchers.prototype.toNotEqual = function(expected) {
   return this.report(!this.env.equals_(this.actual, expected),
     'Expected ' + jasmine.Matchers.pp(expected) + ' to not equal ' + jasmine.Matchers.pp(this.actual) + ', but it does.');
@@ -580,6 +911,12 @@ jasmine.Matchers.prototype.toNotEqual = function(expected) {
 /** @deprecated */
 jasmine.Matchers.prototype.should_not_equal = jasmine.Matchers.prototype.toNotEqual;
 
+/**
+ * Matcher that compares the actual to the expected using a regular expression.  Constructs a RegExp, so takes
+ * a pattern or a String.
+ *
+ * @param reg_exp
+ */
 jasmine.Matchers.prototype.toMatch = function(reg_exp) {
   return this.report((new RegExp(reg_exp).test(this.actual)),
     'Expected ' + jasmine.Matchers.pp(this.actual) + ' to match ' + reg_exp + '.');
@@ -587,6 +924,10 @@ jasmine.Matchers.prototype.toMatch = function(reg_exp) {
 /** @deprecated */
 jasmine.Matchers.prototype.should_match = jasmine.Matchers.prototype.toMatch;
 
+/**
+ * Matcher that compares the actual to the expected using the boolean inverse of jasmine.Matchers.toMatch
+ * @param reg_exp
+ */
 jasmine.Matchers.prototype.toNotMatch = function(reg_exp) {
   return this.report((!new RegExp(reg_exp).test(this.actual)),
     'Expected ' + jasmine.Matchers.pp(this.actual) + ' to not match ' + reg_exp + '.');
@@ -594,6 +935,9 @@ jasmine.Matchers.prototype.toNotMatch = function(reg_exp) {
 /** @deprecated */
 jasmine.Matchers.prototype.should_not_match = jasmine.Matchers.prototype.toNotMatch;
 
+/**
+ * Matcher that compares the acutal to undefined.
+ */
 jasmine.Matchers.prototype.toBeDefined = function() {
   return this.report((this.actual !== undefined),
     'Expected a value to be defined but it was undefined.');
@@ -601,6 +945,10 @@ jasmine.Matchers.prototype.toBeDefined = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.should_be_defined = jasmine.Matchers.prototype.toBeDefined;
 
+/**
+ * Matcher that compares the actual to null.
+ *
+ */
 jasmine.Matchers.prototype.toBeNull = function() {
   return this.report((this.actual === null),
     'Expected a value to be null but it was ' + jasmine.Matchers.pp(this.actual) + '.');
@@ -608,6 +956,9 @@ jasmine.Matchers.prototype.toBeNull = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.should_be_null = jasmine.Matchers.prototype.toBeNull;
 
+/**
+ * Matcher that boolean not-nots the actual.
+ */
 jasmine.Matchers.prototype.toBeTruthy = function() {
   return this.report(!!this.actual,
     'Expected a value to be truthy but it was ' + jasmine.Matchers.pp(this.actual) + '.');
@@ -615,6 +966,9 @@ jasmine.Matchers.prototype.toBeTruthy = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.should_be_truthy = jasmine.Matchers.prototype.toBeTruthy;
 
+/**
+ * Matcher that boolean nots the actual.
+ */
 jasmine.Matchers.prototype.toBeFalsy = function() {
   return this.report(!this.actual,
     'Expected a value to be falsy but it was ' + jasmine.Matchers.pp(this.actual) + '.');
@@ -622,6 +976,9 @@ jasmine.Matchers.prototype.toBeFalsy = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.should_be_falsy = jasmine.Matchers.prototype.toBeFalsy;
 
+/**
+ * Matcher that checks to see if the acutal, a Jasmine spy, was called.
+ */
 jasmine.Matchers.prototype.wasCalled = function() {
   if (!this.actual || !this.actual.isSpy) {
     return this.report(false, 'Expected a spy, but got ' + jasmine.Matchers.pp(this.actual) + '.');
@@ -635,6 +992,9 @@ jasmine.Matchers.prototype.wasCalled = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.was_called = jasmine.Matchers.prototype.wasCalled;
 
+/**
+ * Matcher that checks to see if the acutal, a Jasmine spy, was not called.
+ */
 jasmine.Matchers.prototype.wasNotCalled = function() {
   if (!this.actual || !this.actual.isSpy) {
     return this.report(false, 'Expected a spy, but got ' + jasmine.Matchers.pp(this.actual) + '.');
@@ -645,6 +1005,12 @@ jasmine.Matchers.prototype.wasNotCalled = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.was_not_called = jasmine.Matchers.prototype.wasNotCalled;
 
+/**
+ * Matcher that checks to see if the acutal, a Jasmine spy, was called with a set of parameters.
+ *
+ * @example
+ *
+ */
 jasmine.Matchers.prototype.wasCalledWith = function() {
   if (!this.actual || !this.actual.isSpy) {
     return this.report(false, 'Expected a spy, but got ' + jasmine.Matchers.pp(this.actual) + '.', {
@@ -660,18 +1026,33 @@ jasmine.Matchers.prototype.wasCalledWith = function() {
   });
 };
 
-jasmine.Matchers.prototype.toContain = function(expected) {
-  return this.report(this.env.contains_(this.actual, expected),
-    'Expected ' + jasmine.Matchers.pp(this.actual) + ' to contain ' + jasmine.Matchers.pp(expected) + ', but it does not.', {
-    matcherName: 'toContain', expected: expected, actual: this.actual
+/**
+ * Matcher that checks that the expected item is an element in the actual Array.
+ *
+ * @param {Object} item
+ */
+jasmine.Matchers.prototype.toContain = function(item) {
+  return this.report(this.env.contains_(this.actual, item),
+    'Expected ' + jasmine.Matchers.pp(this.actual) + ' to contain ' + jasmine.Matchers.pp(item) + ', but it does not.', {
+    matcherName: 'toContain', expected: item, actual: this.actual
   });
 };
 
+/**
+ * Matcher that checks that the expected item is NOT an element in the actual Array.
+ *
+ * @param {Object} item
+ */
 jasmine.Matchers.prototype.toNotContain = function(item) {
   return this.report(!this.env.contains_(this.actual, item),
     'Expected ' + jasmine.Matchers.pp(this.actual) + ' not to contain ' + jasmine.Matchers.pp(item) + ', but it does.');
 };
 
+/**
+ * Matcher that checks that the expected exception was thrown by the actual.
+ *
+ * @param {String} expectedException
+ */
 jasmine.Matchers.prototype.toThrow = function(expectedException) {
   var exception = null;
   try {
@@ -880,33 +1261,61 @@ window.clearInterval = function(timeoutKey) {
 };
 
 /**
- * Holds results; allows for the results array to hold another jasmine.NestedResults
+ * Holds results for a set of Jasmine spec. Allows for the results array to hold another jasmine.NestedResults
  *
  * @constructor
  */
 jasmine.NestedResults = function() {
+  /**
+   * The total count of results
+   */
   this.totalCount = 0;
+  /**
+   * Number of passed results
+   */
   this.passedCount = 0;
+  /**
+   * Number of failed results
+   */
   this.failedCount = 0;
+  /**
+   * Was this suite/spec skipped?
+   */
   this.skipped = false;
+  /**
+   * @ignore
+   */
   this.items_ = [];
 };
 
+/**
+ * Roll up the result counts.
+ *
+ * @param result
+ */
 jasmine.NestedResults.prototype.rollupCounts = function(result) {
   this.totalCount += result.totalCount;
   this.passedCount += result.passedCount;
   this.failedCount += result.failedCount;
 };
 
+/**
+ * Tracks a result's message.
+ * @param message
+ */
 jasmine.NestedResults.prototype.log = function(message) {
   this.items_.push(new jasmine.MessageResult(message));
 };
 
+/**
+ * Getter for the results: message & results.
+ */
 jasmine.NestedResults.prototype.getItems = function() {
   return this.items_;
 };
 
 /**
+ * Adds a result, tracking counts (total, passed, & failed)
  * @param {jasmine.ExpectationResult|jasmine.NestedResults} result
  */
 jasmine.NestedResults.prototype.addResult = function(result) {
@@ -925,13 +1334,25 @@ jasmine.NestedResults.prototype.addResult = function(result) {
   this.items_.push(result);
 };
 
+/**
+ * @returns {Boolean} True if <b>everything</b> below passed
+ */
 jasmine.NestedResults.prototype.passed = function() {
   return this.passedCount === this.totalCount;
 };
+/**
+ * Base class for pretty printing for expectation results.
+ */
 jasmine.PrettyPrinter = function() {
   this.ppNestLevel_ = 0;
 };
 
+/**
+ * Formats a value in a nice, human-readable string.
+ *
+ * @param value
+ * @returns {String}
+ */
 jasmine.PrettyPrinter.prototype.format = function(value) {
   if (this.ppNestLevel_ > 40) {
     //    return '(jasmine.pp nested too deeply!)';
@@ -1180,10 +1601,11 @@ jasmine.Runner.prototype.getResults = function() {
   return results;
 };
 /**
- * Spec
- *
- * @constructor
+ * Internal representation of a Jasmine specification, or test.
+ * @private
+ * @constructs
  * @param {jasmine.Env} env
+ * @param {jasmine.Suite} suite
  * @param {String} description
  */
 jasmine.Spec = function(env, suite, description) {
@@ -1226,21 +1648,36 @@ jasmine.Spec.prototype.addToQueue = function(func) {
   return this;
 };
 
-/** @deprecated */
+/**
+ * @private
+ * @deprecated
+ */
 jasmine.Spec.prototype.expects_that = function(actual) {
   return this.expect(actual);
 };
 
+/**
+ * @private
+ * @deprecated
+ */
 jasmine.Spec.prototype.expect = function(actual) {
   return new jasmine.Matchers(this.env, actual, this.results);
 };
 
+/**
+ * @private
+ * @deprecated
+ */
 jasmine.Spec.prototype.waits = function(timeout) {
   this.currentTimeout = timeout;
   this.currentLatchFunction = undefined;
   return this;
 };
 
+/**
+ * @private
+ * @deprecated
+ */
 jasmine.Spec.prototype.waitsFor = function(timeout, latchFunction, message) {
   this.currentTimeout = timeout;
   this.currentLatchFunction = latchFunction;
@@ -1355,7 +1792,7 @@ jasmine.Spec.prototype.removeAllSpies = function() {
 };
 
 /**
- * Description
+ * For storing & executing a Jasmine suite.
  *
  * @constructor
  * @param {jasmine.Env} env

src/ActionCollection.js

@@ -13,6 +13,9 @@ jasmine.ActionCollection = function(env) {
   this.finished = false;
 };
 
+/**
+ * Marks the collection as done & calls the finish callback, if there is one
+ */
 jasmine.ActionCollection.prototype.finish = function() {
   if (this.finishCallback) {
     this.finishCallback();
@@ -20,16 +23,25 @@ jasmine.ActionCollection.prototype.finish = function() {
   this.finished = true;
 };
 
+/**
+ * Starts executing the queue of functions/actions.
+ */
 jasmine.ActionCollection.prototype.execute = function() {
   if (this.actions.length > 0) {
     this.next();
   }
 };
 
+/**
+ * Gets the current action.
+ */
 jasmine.ActionCollection.prototype.getCurrentAction = function() {
   return this.actions[this.index];
 };
 
+/**
+ * Executes the next queued function/action. If there are no more in the queue, calls #finish.
+ */
 jasmine.ActionCollection.prototype.next = function() {
   if (this.index >= this.actions.length) {
     this.finish();

src/Env.js

@@ -1,8 +1,3 @@
-/**
- * Env
- *
- * @constructor
- */
 jasmine.Env = function() {
   this.currentSpec = null;
   this.currentSuite = null;

src/Matchers.js

@@ -1,8 +1,3 @@
-/*
- * jasmine.Matchers methods; add your own by extending jasmine.Matchers.prototype - don't forget to write a test
- *
- */
-
 jasmine.Matchers = function(env, actual, results) {
   this.env = env;
   this.actual = actual;
@@ -23,17 +18,31 @@ jasmine.Matchers.prototype.report = function(result, failing_message, details) {
   return result;
 };
 
+/**
+ * Matcher that compares the actual to the expected using ===.
+ *
+ * @param expected
+ */
 jasmine.Matchers.prototype.toBe = function(expected) {
   return this.report(this.actual === expected, 'Expected<br /><br />' + jasmine.Matchers.pp(expected)
     + '<br /><br />to be the same object as<br /><br />' + jasmine.Matchers.pp(this.actual)
     + '<br />');
 };
 
+/**
+ * Matcher that compares the actual to the expected using !==
+ * @param expected
+ */
 jasmine.Matchers.prototype.toNotBe = function(expected) {
   return this.report(this.actual !== expected, 'Expected<br /><br />' + jasmine.Matchers.pp(expected)
     + '<br /><br />to be a different object from actual, but they were the same.');
 };
 
+/**
+ * Matcher that compares the actual to the expected using common sense equality. Handles Objects, Arrays, etc.
+ *
+ * @param expected
+ */
 jasmine.Matchers.prototype.toEqual = function(expected) {
   var mismatchKeys = [];
   var mismatchValues = [];
@@ -59,6 +68,10 @@ jasmine.Matchers.prototype.toEqual = function(expected) {
 /** @deprecated */
 jasmine.Matchers.prototype.should_equal = jasmine.Matchers.prototype.toEqual;
 
+/**
+ * Matcher that compares the actual to the expected using the ! of jasmine.Matchers.toEqual
+ * @param expected
+ */
 jasmine.Matchers.prototype.toNotEqual = function(expected) {
   return this.report(!this.env.equals_(this.actual, expected),
     'Expected ' + jasmine.Matchers.pp(expected) + ' to not equal ' + jasmine.Matchers.pp(this.actual) + ', but it does.');
@@ -66,6 +79,12 @@ jasmine.Matchers.prototype.toNotEqual = function(expected) {
 /** @deprecated */
 jasmine.Matchers.prototype.should_not_equal = jasmine.Matchers.prototype.toNotEqual;
 
+/**
+ * Matcher that compares the actual to the expected using a regular expression.  Constructs a RegExp, so takes
+ * a pattern or a String.
+ *
+ * @param reg_exp
+ */
 jasmine.Matchers.prototype.toMatch = function(reg_exp) {
   return this.report((new RegExp(reg_exp).test(this.actual)),
     'Expected ' + jasmine.Matchers.pp(this.actual) + ' to match ' + reg_exp + '.');
@@ -73,6 +92,10 @@ jasmine.Matchers.prototype.toMatch = function(reg_exp) {
 /** @deprecated */
 jasmine.Matchers.prototype.should_match = jasmine.Matchers.prototype.toMatch;
 
+/**
+ * Matcher that compares the actual to the expected using the boolean inverse of jasmine.Matchers.toMatch
+ * @param reg_exp
+ */
 jasmine.Matchers.prototype.toNotMatch = function(reg_exp) {
   return this.report((!new RegExp(reg_exp).test(this.actual)),
     'Expected ' + jasmine.Matchers.pp(this.actual) + ' to not match ' + reg_exp + '.');
@@ -80,6 +103,9 @@ jasmine.Matchers.prototype.toNotMatch = function(reg_exp) {
 /** @deprecated */
 jasmine.Matchers.prototype.should_not_match = jasmine.Matchers.prototype.toNotMatch;
 
+/**
+ * Matcher that compares the acutal to undefined.
+ */
 jasmine.Matchers.prototype.toBeDefined = function() {
   return this.report((this.actual !== undefined),
     'Expected a value to be defined but it was undefined.');
@@ -87,6 +113,10 @@ jasmine.Matchers.prototype.toBeDefined = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.should_be_defined = jasmine.Matchers.prototype.toBeDefined;
 
+/**
+ * Matcher that compares the actual to null.
+ *
+ */
 jasmine.Matchers.prototype.toBeNull = function() {
   return this.report((this.actual === null),
     'Expected a value to be null but it was ' + jasmine.Matchers.pp(this.actual) + '.');
@@ -94,6 +124,9 @@ jasmine.Matchers.prototype.toBeNull = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.should_be_null = jasmine.Matchers.prototype.toBeNull;
 
+/**
+ * Matcher that boolean not-nots the actual.
+ */
 jasmine.Matchers.prototype.toBeTruthy = function() {
   return this.report(!!this.actual,
     'Expected a value to be truthy but it was ' + jasmine.Matchers.pp(this.actual) + '.');
@@ -101,6 +134,9 @@ jasmine.Matchers.prototype.toBeTruthy = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.should_be_truthy = jasmine.Matchers.prototype.toBeTruthy;
 
+/**
+ * Matcher that boolean nots the actual.
+ */
 jasmine.Matchers.prototype.toBeFalsy = function() {
   return this.report(!this.actual,
     'Expected a value to be falsy but it was ' + jasmine.Matchers.pp(this.actual) + '.');
@@ -108,6 +144,9 @@ jasmine.Matchers.prototype.toBeFalsy = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.should_be_falsy = jasmine.Matchers.prototype.toBeFalsy;
 
+/**
+ * Matcher that checks to see if the acutal, a Jasmine spy, was called.
+ */
 jasmine.Matchers.prototype.wasCalled = function() {
   if (!this.actual || !this.actual.isSpy) {
     return this.report(false, 'Expected a spy, but got ' + jasmine.Matchers.pp(this.actual) + '.');
@@ -121,6 +160,9 @@ jasmine.Matchers.prototype.wasCalled = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.was_called = jasmine.Matchers.prototype.wasCalled;
 
+/**
+ * Matcher that checks to see if the acutal, a Jasmine spy, was not called.
+ */
 jasmine.Matchers.prototype.wasNotCalled = function() {
   if (!this.actual || !this.actual.isSpy) {
     return this.report(false, 'Expected a spy, but got ' + jasmine.Matchers.pp(this.actual) + '.');
@@ -131,6 +173,12 @@ jasmine.Matchers.prototype.wasNotCalled = function() {
 /** @deprecated */
 jasmine.Matchers.prototype.was_not_called = jasmine.Matchers.prototype.wasNotCalled;
 
+/**
+ * Matcher that checks to see if the acutal, a Jasmine spy, was called with a set of parameters.
+ *
+ * @example
+ *
+ */
 jasmine.Matchers.prototype.wasCalledWith = function() {
   if (!this.actual || !this.actual.isSpy) {
     return this.report(false, 'Expected a spy, but got ' + jasmine.Matchers.pp(this.actual) + '.', {
@@ -146,18 +194,33 @@ jasmine.Matchers.prototype.wasCalledWith = function() {
   });
 };
 
-jasmine.Matchers.prototype.toContain = function(expected) {
-  return this.report(this.env.contains_(this.actual, expected),
-    'Expected ' + jasmine.Matchers.pp(this.actual) + ' to contain ' + jasmine.Matchers.pp(expected) + ', but it does not.', {
-    matcherName: 'toContain', expected: expected, actual: this.actual
+/**
+ * Matcher that checks that the expected item is an element in the actual Array.
+ *
+ * @param {Object} item
+ */
+jasmine.Matchers.prototype.toContain = function(item) {
+  return this.report(this.env.contains_(this.actual, item),
+    'Expected ' + jasmine.Matchers.pp(this.actual) + ' to contain ' + jasmine.Matchers.pp(item) + ', but it does not.', {
+    matcherName: 'toContain', expected: item, actual: this.actual
   });
 };
 
+/**
+ * Matcher that checks that the expected item is NOT an element in the actual Array.
+ *
+ * @param {Object} item
+ */
 jasmine.Matchers.prototype.toNotContain = function(item) {
   return this.report(!this.env.contains_(this.actual, item),
     'Expected ' + jasmine.Matchers.pp(this.actual) + ' not to contain ' + jasmine.Matchers.pp(item) + ', but it does.');
 };
 
+/**
+ * Matcher that checks that the expected exception was thrown by the actual.
+ *
+ * @param {String} expectedException
+ */
 jasmine.Matchers.prototype.toThrow = function(expectedException) {
   var exception = null;
   try {

src/NestedResults.js

@@ -1,31 +1,59 @@
 /**
- * Holds results; allows for the results array to hold another jasmine.NestedResults
+ * Holds results for a set of Jasmine spec. Allows for the results array to hold another jasmine.NestedResults
  *
  * @constructor
  */
 jasmine.NestedResults = function() {
+  /**
+   * The total count of results
+   */
   this.totalCount = 0;
+  /**
+   * Number of passed results
+   */
   this.passedCount = 0;
+  /**
+   * Number of failed results
+   */
   this.failedCount = 0;
+  /**
+   * Was this suite/spec skipped?
+   */
   this.skipped = false;
+  /**
+   * @ignore
+   */
   this.items_ = [];
 };
 
+/**
+ * Roll up the result counts.
+ *
+ * @param result
+ */
 jasmine.NestedResults.prototype.rollupCounts = function(result) {
   this.totalCount += result.totalCount;
   this.passedCount += result.passedCount;
   this.failedCount += result.failedCount;
 };
 
+/**
+ * Tracks a result's message.
+ * @param message
+ */
 jasmine.NestedResults.prototype.log = function(message) {
   this.items_.push(new jasmine.MessageResult(message));
 };
 
+/**
+ * Getter for the results: message & results.
+ */
 jasmine.NestedResults.prototype.getItems = function() {
   return this.items_;
 };
 
 /**
+ * Adds a result, tracking counts (total, passed, & failed)
  * @param {jasmine.ExpectationResult|jasmine.NestedResults} result
  */
 jasmine.NestedResults.prototype.addResult = function(result) {
@@ -44,6 +72,9 @@ jasmine.NestedResults.prototype.addResult = function(result) {
   this.items_.push(result);
 };
 
+/**
+ * @returns {Boolean} True if <b>everything</b> below passed
+ */
 jasmine.NestedResults.prototype.passed = function() {
   return this.passedCount === this.totalCount;
 };

src/PrettyPrinter.js

@@ -1,7 +1,16 @@
+/**
+ * Base class for pretty printing for expectation results.
+ */
 jasmine.PrettyPrinter = function() {
   this.ppNestLevel_ = 0;
 };
 
+/**
+ * Formats a value in a nice, human-readable string.
+ *
+ * @param value
+ * @returns {String}
+ */
 jasmine.PrettyPrinter.prototype.format = function(value) {
   if (this.ppNestLevel_ > 40) {
     //    return '(jasmine.pp nested too deeply!)';

src/Spec.js

@@ -1,8 +1,9 @@
 /**
- * Spec
- *
- * @constructor
+ * Internal representation of a Jasmine specification, or test.
+ * @private
+ * @constructs
  * @param {jasmine.Env} env
+ * @param {jasmine.Suite} suite
  * @param {String} description
  */
 jasmine.Spec = function(env, suite, description) {
@@ -45,21 +46,36 @@ jasmine.Spec.prototype.addToQueue = function(func) {
   return this;
 };
 
-/** @deprecated */
+/**
+ * @private
+ * @deprecated
+ */
 jasmine.Spec.prototype.expects_that = function(actual) {
   return this.expect(actual);
 };
 
+/**
+ * @private
+ * @deprecated
+ */
 jasmine.Spec.prototype.expect = function(actual) {
   return new jasmine.Matchers(this.env, actual, this.results);
 };
 
+/**
+ * @private
+ * @deprecated
+ */
 jasmine.Spec.prototype.waits = function(timeout) {
   this.currentTimeout = timeout;
   this.currentLatchFunction = undefined;
   return this;
 };
 
+/**
+ * @private
+ * @deprecated
+ */
 jasmine.Spec.prototype.waitsFor = function(timeout, latchFunction, message) {
   this.currentTimeout = timeout;
   this.currentLatchFunction = latchFunction;

src/Suite.js

@@ -1,5 +1,5 @@
 /**
- * Description
+ * For storing & executing a Jasmine suite.
  *
  * @constructor
  * @param {jasmine.Env} env

src/base.js

@@ -1,14 +1,25 @@
-/*
- * Jasmine internal classes & objects
+/**
+ * Top level namespace for Jasmine, a lightweight JavaScript BDD/spec/testing framework.
+ * 
+ * @namespace
  */
-
-/** @namespace */
 var jasmine = {};
 
+/**
+ * @private
+ */
 jasmine.unimplementedMethod_ = function() {
   throw new Error("unimplemented method");
 };
 
+/**
+ * Allows for bound functions to be comapred.  Internal use only.
+ *
+ * @ignore
+ * @private
+ * @param base {Object} bound 'this' for the function
+ * @param name {Function} function to find
+ */
 jasmine.bindOriginal_ = function(base, name) {
   var original = base[name];
   return function() {
@@ -35,10 +46,19 @@ jasmine.ExpectationResult = function(passed, message, details) {
   this.trace = new Error(message); // todo: test better
 };
 
+/**
+ * Getter for the Jasmine environment. Ensures one gets created
+ */
 jasmine.getEnv = function() {
   return jasmine.currentEnv_ = jasmine.currentEnv_ || new jasmine.Env();
 };
 
+/**
+ * @ignore
+ * @private
+ * @param value
+ * @returns {Boolean}
+ */
 jasmine.isArray_ = function(value) {
   return value &&
   typeof value === 'object' &&
@@ -47,70 +67,249 @@ jasmine.isArray_ = function(value) {
   !(value.propertyIsEnumerable('length'));
 };
 
+/**
+ * Pretty printer for expecations.  Takes any object and turns it into a human-readable string.
+ *
+ * @param value {Object} an object to be outputted
+ * @returns {String}
+ */
 jasmine.pp = function(value) {
   var stringPrettyPrinter = new jasmine.StringPrettyPrinter();
   stringPrettyPrinter.format(value);
   return stringPrettyPrinter.string;
 };
 
+/**
+ * Returns true if the object is a DOM Node.
+ *
+ * @param {Object} obj object to check
+ * @returns {Boolean}
+ */
 jasmine.isDomNode = function(obj) {
   return obj['nodeType'] > 0;
 };
 
+/**
+ * Returns a matchable 'generic' object of the class type.  For use in expecations of type when values don't matter.
+ *
+ * @example
+ * // don't care about which function is passed in, as long as it's a function
+ * expect(mySpy).wasCalledWith(jasmine.any(Function));
+ *
+ * @param {Class} clazz
+ * @returns matchable object of the type clazz
+ */
 jasmine.any = function(clazz) {
   return new jasmine.Matchers.Any(clazz);
 };
 
+/**
+ * Jasmine Spies are test doubles that can act as stubs, spies, fakes or when used in an expecation, mocks.
+ *
+ * Spies should be created in test setup, before expectations.  They can then be checked, using the standard Jasmine
+ * expectation syntax. Spies can be checked if they were called or not and what the calling params were.
+ *
+ * A Spy has the following mehtod: wasCalled, callCount, mostRecentCall, and argsForCall (see docs)
+ * Spies are torn down at the end of every spec.
+ *
+ * Note: Do <b>not</b> call new jasmine.Spy() directly - a spy must be created using spyOn, jasmine.createSpy or jasmine.createSpyObj.
+ * 
+ * @example
+ * // a stub
+ * var myStub = jasmine.createSpy('myStub');  // can be used anywhere
+ *
+ * // spy example
+ * var foo = {
+ *   not: function(bool) { return !bool; }
+ * }
+ *
+ * // actual foo.not will not be called, execution stops
+ * spyOn(foo, 'not');
+
+ // foo.not spied upon, execution will continue to implementation
+ * spyOn(foo, 'not').andCallThrough();
+ *
+ * // fake example
+ * var foo = {
+ *   not: function(bool) { return !bool; }
+ * }
+ *
+ * // foo.not(val) will return val
+ * spyOn(foo, 'not').andCallFake(function(value) {return value;});
+ *
+ * // mock example
+ * foo.not(7 == 7);
+ * expect(foo.not).wasCalled();
+ * expect(foo.not).wasCalledWith(true);
+ *
+ * @constructor
+ * @see spyOn, jasmine.createSpy, jasmine.createSpyObj
+ * @param {String} name
+ */
+jasmine.Spy = function(name) {
+  /**
+   * The name of the spy, if provided.
+   */
+  this.identity = name || 'unknown';
+  /**
+   *  Is this Object a spy?
+   */
+  this.isSpy = true;
+  /**
+   * The acutal function this spy stubs.
+   */
+  this.plan = function() {};
+  /**
+   * Tracking of the most recent call to the spy.
+   * @example
+   * var mySpy = jasmine.createSpy('foo');
+   * mySpy(1, 2);
+   * mySpy.mostRecentCall.args = [1, 2];
+   */
+  this.mostRecentCall = {};
+
+  /**
+   * Holds arguments for each call to the spy, indexed by call count
+   * @example
+   * var mySpy = jasmine.createSpy('foo');
+   * mySpy(1, 2);
+   * mySpy(7, 8);
+   * mySpy.mostRecentCall.args = [7, 8];
+   * mySpy.argsForCall[0] = [1, 2];
+   * mySpy.argsForCall[1] = [7, 8];
+   */
+  this.argsForCall = [];
+};
+
+/**
+ * Tells a spy to call through to the actual implemenatation.
+ *
+ * @example
+ * var foo = {
+ *   bar: function() { // do some stuff }
+ * }
+ * 
+ * // defining a spy on an existing property: foo.bar
+ * spyOn(foo, 'bar').andCallThrough();
+ */
+jasmine.Spy.prototype.andCallThrough = function() {
+  this.plan = this.originalValue;
+  return this;
+};
+
+/**
+ * For setting the return value of a spy.
+ *
+ * @example
+ * // defining a spy from scratch: foo() returns 'baz'
+ * var foo = jasmine.createSpy('spy on foo').andReturn('baz');
+ *
+ * // defining a spy on an existing property: foo.bar() returns 'baz'
+ * spyOn(foo, 'bar').andReturn('baz');
+ *
+ * @param {Object} value
+ */
+jasmine.Spy.prototype.andReturn = function(value) {
+  this.plan = function() {
+    return value;
+  };
+  return this;
+};
+
+/**
+ * For throwing an exception when a spy is called.
+ *
+ * @example
+ * // defining a spy from scratch: foo() throws an exception w/ message 'ouch'
+ * var foo = jasmine.createSpy('spy on foo').andThrow('baz');
+ *
+ * // defining a spy on an existing property: foo.bar() throws an exception w/ message 'ouch'
+ * spyOn(foo, 'bar').andThrow('baz');
+ *
+ * @param {String} exceptionMsg
+ */
+jasmine.Spy.prototype.andThrow = function(exceptionMsg) {
+  this.plan = function() {
+    throw exceptionMsg;
+  };
+  return this;
+};
+
+/**
+ * Calls an alternate implementation when a spy is called.
+ *
+ * @example
+ * var baz = function() {
+ *   // do some stuff, return something
+ * }
+ * // defining a spy from scratch: foo() calls the function baz
+ * var foo = jasmine.createSpy('spy on foo').andCall(baz);
+ *
+ * // defining a spy on an existing property: foo.bar() calls an anonymnous function
+ * spyOn(foo, 'bar').andCall(function() { return 'baz';} );
+ *
+ * @param {Function} fakeFunc
+ */
+jasmine.Spy.prototype.andCallFake = function(fakeFunc) {
+  this.plan = fakeFunc;
+  return this;
+};
+
+/**
+ * Resets all of a spy's the tracking variables so that it can be used again.
+ *
+ * @example
+ * spyOn(foo, 'bar');
+ *
+ * foo.bar();
+ *
+ * expect(foo.bar.callCount).toEqual(1);
+ *
+ * foo.bar.reset();
+ *
+ * expect(foo.bar.callCount).toEqual(0);
+ */
+jasmine.Spy.prototype.reset = function() {
+  this.wasCalled = false;
+  this.callCount = 0;
+  this.argsForCall = [];
+  this.mostRecentCall = {};
+};
+
 jasmine.createSpy = function(name) {
+
   var spyObj = function() {
     spyObj.wasCalled = true;
     spyObj.callCount++;
     var args = jasmine.util.argsToArray(arguments);
-    spyObj.mostRecentCall = {
-      object: this,
-      args: args
-    };
+    //spyObj.mostRecentCall = {
+    //  object: this,
+    //  args: args
+    //};
+    spyObj.mostRecentCall.object = this;
+    spyObj.mostRecentCall.args = args;
     spyObj.argsForCall.push(args);
     return spyObj.plan.apply(this, arguments);
   };
 
-  spyObj.identity = name || 'unknown';
-  spyObj.isSpy = true;
+  var spy = new jasmine.Spy(name);
   
-  spyObj.plan = function() {
-  };
+  for(var prop in spy) {
+    spyObj[prop] = spy[prop];
+  }
   
-  spyObj.andCallThrough = function() {
-    spyObj.plan = spyObj.originalValue;
-    return spyObj;
-  };
-  spyObj.andReturn = function(value) {
-    spyObj.plan = function() {
-      return value;
-    };
-    return spyObj;
-  };
-  spyObj.andThrow = function(exceptionMsg) {
-    spyObj.plan = function() {
-      throw exceptionMsg;
-    };
-    return spyObj;
-  };
-  spyObj.andCallFake = function(fakeFunc) {
-    spyObj.plan = fakeFunc;
-    return spyObj;
-  };
-  spyObj.reset = function() {
-    spyObj.wasCalled = false;
-    spyObj.callCount = 0;
-    spyObj.argsForCall = [];
-    spyObj.mostRecentCall = {};
-  };
   spyObj.reset();
 
   return spyObj;
 };
 
+/**
+ * Creates a more complicated spy: an Object that has every property a function that is a spy.  Used for stubbing something
+ * large in one call.
+ *
+ * @param {String} baseName name of spy class
+ * @param {Array} methodNames array of names of methods to make spies
+ */
 jasmine.createSpyObj = function(baseName, methodNames) {
   var obj = {};
   for (var i = 0; i < methodNames.length; i++) {
@@ -123,50 +322,146 @@ jasmine.log = function(message) {
   jasmine.getEnv().currentSpec.getResults().log(message);
 };
 
+/**
+ * Function that installs a spy on an existing object's method name.  Used within a Spec to create a spy.
+ *
+ * @example
+ * // spy example
+ * var foo = {
+ *   not: function(bool) { return !bool; }
+ * }
+ * spyOn(foo, 'not'); // actual foo.not will not be called, execution stops
+ *
+ * @see jasmine.createSpy
+ * @param obj
+ * @param methodName
+ * @returns a Jasmine spy that can be chained with all spy methods
+ */
 var spyOn = function(obj, methodName) {
   return jasmine.getEnv().currentSpec.spyOn(obj, methodName);
 };
 
+/**
+ * Creates a Jasmine spec that will be added to the current suite.
+ *
+ * // TODO: pending tests
+ *
+ * @example
+ * it('should be true', function() {
+ *   expect(true).toEqual(true);
+ * });
+ *
+ * @param {String} desc description of this specification
+ * @param {Function} func defines the preconditions and expectations of the spec
+ */
 var it = function(desc, func) {
   return jasmine.getEnv().it(desc, func);
 };
 
+/**
+ * Creates a <em>disabled</em> Jasmine spec.
+ *
+ * A convenience method that allows existing specs to be disabled temporarily during development.
+ *
+ * @param {String} desc description of this specification
+ * @param {Function} func defines the preconditions and expectations of the spec
+ */
 var xit = function(desc, func) {
   return jasmine.getEnv().xit(desc, func);
 };
 
+/**
+ * Starts a chain for a Jasmine expectation.
+ *
+ * It is passed an Object that is the actual value and should chain to one of the many
+ * jasmine.Matchers functions.
+ *
+ * @param {Object} actual Actual value to test against and expected value
+ */
 var expect = function(actual) {
   return jasmine.getEnv().currentSpec.expect(actual);
 };
 
+/**
+ * Defines part of a jasmine spec.  Used in cominbination with waits or waitsFor in asynchrnous specs.
+ *
+ * @param {Function} func Function that defines part of a jasmine spec.
+ */
 var runs = function(func) {
   jasmine.getEnv().currentSpec.runs(func);
 };
 
+/**
+ * Waits for a timeout before moving to the next runs()-defined block.
+ * @param {Number} timeout
+ */
 var waits = function(timeout) {
   jasmine.getEnv().currentSpec.waits(timeout);
 };
 
+/**
+ * Waits for the latchFunction to return true before proceeding to the next runs()-defined block.
+ *  
+ * @param {Number} timeout
+ * @param {Function} latchFunction
+ * @param {String} message
+ */
 var waitsFor = function(timeout, latchFunction, message) {
   jasmine.getEnv().currentSpec.waitsFor(timeout, latchFunction, message);
 };
 
+/**
+ * A function that is called before each spec in a suite.
+ *
+ * Used for spec setup, including validating assumptions.
+ *
+ * @param {Function} beforeEachFunction
+ */
 var beforeEach = function(beforeEachFunction) {
   jasmine.getEnv().beforeEach(beforeEachFunction);
 };
 
+/**
+ * A function that is called after each spec in a suite.
+ *
+ * Used for restoring any state that is hijacked during spec execution.
+ *
+ * @param {Function} afterEachFunction
+ */
 var afterEach = function(afterEachFunction) {
   jasmine.getEnv().afterEach(afterEachFunction);
 };
 
+/**
+ * Defines a suite of specifications.
+ *
+ * Stores the description and all defined specs in the Jasmine environment as one suite of specs. Variables declared
+ * are accessible by calls to beforeEach, it, and afterEach. Describe blocks can be nested, allowing for specialization
+ * of setup in some tests.
+ *
+ * @example
+ * // TODO: a simple suite
+ *
+ * // TODO: a simple suite with a nested describe block
+ *
+ * @param {String} description A string, usually the class under test.
+ * @param {Function} specDefinitions function that defines several specs.
+ */
 var describe = function(description, specDefinitions) {
   return jasmine.getEnv().describe(description, specDefinitions);
 };
 
+/**
+ * Disables a suite of specifications.  Used to disable some suites in a file, or files, temporarily during development.
+ *
+ * @param {String} description A string, usually the class under test.
+ * @param {Function} specDefinitions function that defines several specs.
+ */
 var xdescribe = function(description, specDefinitions) {
   return jasmine.getEnv().xdescribe(description, specDefinitions);
 };
 
+
 jasmine.XmlHttpRequest = XMLHttpRequest;
 
 // Provide the XMLHttpRequest class for IE 5.x-6.x:
@@ -190,6 +485,13 @@ if (typeof XMLHttpRequest == "undefined") jasmine.XmlHttpRequest = function() {
   throw new Error("This browser does not support XMLHttpRequest.");
 };
 
+/**
+ * Adds suite files to an HTML document so that they are executed, thus adding them to the current
+ * Jasmine environment.
+ *
+ * @param {String} url path to the file to include
+ * @param {Boolean} opt_global
+ */
 jasmine.include = function(url, opt_global) {
   if (opt_global) {
     document.write('<script type="text/javascript" src="' + url + '"></' + 'script>');

src/util.js

@@ -1,6 +1,15 @@
-/** @namespace */
+/**
+ * @namespace
+ */
 jasmine.util = {};
 
+/**
+ * Declare that a child class inherite it's prototype from the parent class.
+ *
+ * @private
+ * @param {Function} childClass
+ * @param {Function} parentClass
+ */
 jasmine.util.inherit = function(childClass, parentClass) {
   var subclass = function() {
   };