Update jsDocs to something close to full coverage for public API

- #596

src/core/Env.js

@@ -273,9 +273,10 @@ getJasmineRequireObj().Env = function(j$) {
     };
 
     /**
+     * Add a custom reporter to the Jasmine environment.
      * @name Env#addReporter
      * @function
-     * @tutorial addReporter
+     * @see custom_reporter
      */
     this.addReporter = function(reporterToAdd) {
       reporter.addReporter(reporterToAdd);

src/core/JsApiReporter.js

@@ -36,8 +36,10 @@ getJasmineRequireObj().JsApiReporter = function() {
     };
 
     /**
+     * Get the current status for the Jasmine environment.
      * @name jsApiReporter#status
      * @function
+     * @return {String} - One of `loaded`, `started`, or `done`
      */
     this.status = function() {
       return status;
@@ -55,8 +57,14 @@ getJasmineRequireObj().JsApiReporter = function() {
     };
 
     /**
+     * Get the results for a set of suites.
+     *
+     * Retrievable in slices for easier serialization.
      * @name jsApiReporter#suiteResults
      * @function
+     * @param {Number} index - The position in the suites list to start from.
+     * @param {Number} length - Maximum number of suite results to return.
+     * @return {Object[]}
      */
     this.suiteResults = function(index, length) {
       return suites.slice(index, index + length);
@@ -67,6 +75,12 @@ getJasmineRequireObj().JsApiReporter = function() {
       suites_hash[result.id] = result;
     }
 
+    /**
+     * Get all of the suites in a single object, with their `id` as the key.
+     * @name jsApiReporter#suites
+     * @function
+     * @return {Object}
+     */
     this.suites = function() {
       return suites_hash;
     };
@@ -77,14 +91,36 @@ getJasmineRequireObj().JsApiReporter = function() {
       specs.push(result);
     };
 
+    /**
+     * Get the results for a set of specs.
+     *
+     * Retrievable in slices for easier serialization.
+     * @name jsApiReporter#specResults
+     * @function
+     * @param {Number} index - The position in the specs list to start from.
+     * @param {Number} length - Maximum number of specs results to return.
+     * @return {Object[]}
+     */
     this.specResults = function(index, length) {
       return specs.slice(index, index + length);
     };
 
+    /**
+     * Get all spec results.
+     * @name jsApiReporter#specs
+     * @function
+     * @return {Object[]}
+     */
     this.specs = function() {
       return specs;
     };
 
+    /**
+     * Get the number of milliseconds it took for the full Jasmine suite to run.
+     * @name jsApiReporter#executionTime
+     * @function
+     * @return {Number}
+     */
     this.executionTime = function() {
       return executionTime;
     };

src/core/base.js

@@ -4,14 +4,19 @@ getJasmineRequireObj().base = function(j$, jasmineGlobal) {
   };
 
   /**
+   * Maximum object depth the pretty printer will print to.
+   * Set this to a lower value to speed up pretty printing if you have large objects.
    * @name jasmine.MAX_PRETTY_PRINT_DEPTH
    */
   j$.MAX_PRETTY_PRINT_DEPTH = 40;
   /**
+   * Maximum number of array elements to display when pretty printing objects.
+   * Elements past this number will be ellipised.
    * @name jasmine.MAX_PRETTY_PRINT_ARRAY_LENGTH
    */
   j$.MAX_PRETTY_PRINT_ARRAY_LENGTH = 100;
   /**
+   * Default number of milliseconds Jasmine will wait for an asynchronous spec to complete.
    * @name jasmine.DEFAULT_TIMEOUT_INTERVAL
    */
   j$.DEFAULT_TIMEOUT_INTERVAL = 5000;
@@ -75,14 +80,19 @@ getJasmineRequireObj().base = function(j$, jasmineGlobal) {
   };
 
   /**
+   * Get a matcher, usable in any {@link matchers|matcher} that uses Jasmine's equality (e.g. {@link matchers#toEqual|toEqual}, {@link matchers#toContain|toContain}, or {@link matchers#toHaveBeenCalledWith|toHaveBeenCalledWith}),
+   * that will succeed if the actual value being compared is an instance of the specified class/constructor.
    * @name jasmine.any
    * @function
+   * @param {Constructor} clazz - The constructor to check against.
    */
   j$.any = function(clazz) {
     return new j$.Any(clazz);
   };
 
   /**
+   * Get a matcher, usable in any {@link matchers|matcher} that uses Jasmine's equality (e.g. {@link matchers#toEqual|toEqual}, {@link matchers#toContain|toContain}, or {@link matchers#toHaveBeenCalledWith|toHaveBeenCalledWith}),
+   * that will succeed if the actual value being compared is not `null` and not `undefined`.
    * @name jasmine.anything
    * @function
    */
@@ -91,32 +101,44 @@ getJasmineRequireObj().base = function(j$, jasmineGlobal) {
   };
 
   /**
+   * Get a matcher, usable in any {@link matchers|matcher} that uses Jasmine's equality (e.g. {@link matchers#toEqual|toEqual}, {@link matchers#toContain|toContain}, or {@link matchers#toHaveBeenCalledWith|toHaveBeenCalledWith}),
+   * that will succeed if the actual value being compared contains at least the keys and values.
    * @name jasmine.objectContaining
    * @function
+   * @param {Object} sample - The subset of properties that _must_ be in the actual.
    */
   j$.objectContaining = function(sample) {
     return new j$.ObjectContaining(sample);
   };
 
   /**
+   * Get a matcher, usable in any {@link matchers|matcher} that uses Jasmine's equality (e.g. {@link matchers#toEqual|toEqual}, {@link matchers#toContain|toContain}, or {@link matchers#toHaveBeenCalledWith|toHaveBeenCalledWith}),
+   * that will succeed if the actual value is a `String` that matches the `RegExp` or `String`.
    * @name jasmine.stringMatching
    * @function
+   * @param {RegExp|String} expected
    */
   j$.stringMatching = function(expected) {
     return new j$.StringMatching(expected);
   };
 
   /**
+   * Get a matcher, usable in any {@link matchers|matcher} that uses Jasmine's equality (e.g. {@link matchers#toEqual|toEqual}, {@link matchers#toContain|toContain}, or {@link matchers#toHaveBeenCalledWith|toHaveBeenCalledWith}),
+   * that will succeed if the actual value is an `Array` that contains at least the elements in the sample.
    * @name jasmine.arrayContaining
    * @function
+   * @param {Array} sample
    */
   j$.arrayContaining = function(sample) {
     return new j$.ArrayContaining(sample);
   };
 
   /**
+   * Create a bare {@link Spy} object. This won't be installed anywhere and will not have any implementation behind it.
    * @name jasmine.createSpy
    * @function
+   * @param {String} [name] - Name to give the spy. This will be displayed in failure messages.
+   * @param {Function} [originalFn] - Function to act as the real implementation.
    * @return {Spy}
    */
   j$.createSpy = function(name, originalFn) {
@@ -132,8 +154,12 @@ getJasmineRequireObj().base = function(j$, jasmineGlobal) {
   };
 
   /**
+   * Create an object with multiple {@link Spy}s as its members.
    * @name jasmine.createSpyObj
    * @function
+   * @param {String} [baseName] - Base name for the spies in the object.
+   * @param {String[]|Object} methodNames - Array of method names to create spies for, or Object whose keys will be method names and values the {@link Spy#and#returnValue|returnValue}.
+   * @return {Object}
    */
   j$.createSpyObj = function(baseName, methodNames) {
     var baseNameIsCollection = j$.isObject_(baseName) || j$.isArray_(baseName);

src/core/requireInterface.js

@@ -1,8 +1,9 @@
 getJasmineRequireObj().interface = function(jasmine, env) {
   var jasmineInterface = {
     /**
-     * Create a suite of specs
+     * Create a group of specs (often called a suite).
      *
+     * Calls to `describe` can be nested within other calls to compose your suite as a tree.
      * @name describe
      * @function
      * @global
@@ -31,7 +32,7 @@ getJasmineRequireObj().interface = function(jasmine, env) {
      * A focused [`describe`]{@link describe}
      *
      * If suites or specs are focused, only those that are focused will be executed
-     * @see {fit}
+     * @see fit
      * @name fdescribe
      * @function
      * @global
@@ -43,7 +44,9 @@ getJasmineRequireObj().interface = function(jasmine, env) {
     },
 
     /**
-     * A single spec
+     * Define a single spec. A spec should contain one or more {@link expect|expectations} that test the state of the code.
+     *
+     * A spec whose expectations all succeed will be passing and a spec with any failures will fail.
      * @name it
      * @function
      * @global
@@ -208,24 +211,33 @@ getJasmineRequireObj().interface = function(jasmine, env) {
   };
 
   /**
+   * Add a custom equality tester for the current scope of specs.
+   *
+   * _Note:_ This is only callable from within a {@link beforeEach}, {@link it}, or {@link beforeAll}.
    * @name jasmine.addCustomEqualityTester
    * @function
-   * @tutorial addCustomEqualityTester
+   * @param {Function} tester - A function which takes two arguments to compare and returns a `true` or `false` comparison result if it knows how to compare them, and `undefined` otherwise.
+   * @see custom_equality
    */
   jasmine.addCustomEqualityTester = function(tester) {
     env.addCustomEqualityTester(tester);
   };
 
   /**
+   * Add custom matchers for the current scope of specs.
+   *
+   * _Note:_ This is only callable from within a {@link beforeEach}, {@link it}, or {@link beforeAll}.
    * @name jasmine.addMatchers
    * @function
-   * @tutorial addMatchers
+   * @param {Object} matchers - Keys from this object will be the new matcher names.
+   * @see custom_matcher
    */
   jasmine.addMatchers = function(matchers) {
     return env.addMatchers(matchers);
   };
 
   /**
+   * Get the currently booted mock {Clock} for this Jasmine environment.
    * @name jasmine.clock
    * @function
    * @returns {Clock}