Initial API docs for the Jasmine class

lib/jasmine.js

@@ -8,6 +8,25 @@ var path = require('path'),
 module.exports = Jasmine;
 module.exports.ConsoleReporter = require('./reporters/console_reporter');
 
+/**
+ * Options for the {@link Jasmine} constructor
+ * @name JasmineOptions
+ * @interface
+ */
+/**
+ * The path to the project's base directory. This can be absolute or relative
+ * to the current working directory. If it isn't specified, the current working
+ * directory will be used.
+ * @name JasmineOptions#projectBaseDir
+ * @type (string | undefined)
+ */
+
+/**
+ * @classdesc Configures, builds, and executes a Jasmine test suite
+ * @param {(JasmineOptions | undefined)} options
+ * @constructor
+ * @name Jasmine
+ */
 function Jasmine(options) {
   options = options || {};
   this.loader = options.loader || new Loader();
@@ -35,37 +54,89 @@ function Jasmine(options) {
   });
   this.checkExit = checkExit(this);
 
+  /**
+   * @function
+   * @name Jasmine#coreVersion
+   * @return {string} The version of jasmine-core in use
+   */
   this.coreVersion = function() {
     return jasmineCore.version();
   };
 }
 
+/**
+ * Sets whether to randomize the order of specs.
+ * @function
+ * @name Jasmine#randomizeTests
+ * @deprecated Use the random option with {@link Jasmine#loadConfig} or a
+ * config file instead.
+ * @param {boolean} value Whether to randomize
+ */
 Jasmine.prototype.randomizeTests = function(value) {
   this.env.configure({random: value});
 };
 
+/**
+ * Sets the random seed.
+ * @function
+ * @name Jasmine#seed
+ * @deprecated Use the seed option with {@link Jasmine#loadConfig} or a
+ * config file instead.
+ * @param {number} seed The random seed
+ */
 Jasmine.prototype.seed = function(value) {
   this.env.configure({seed: value});
 };
 
+/**
+ * Sets whether to show colors in the console reporter.
+ * @function
+ * @name Jasmine#showColors
+ * @param {boolean} value Whether to show colors
+ */
 Jasmine.prototype.showColors = function(value) {
   this.showingColors = value;
 };
 
+/**
+ * Adds a spec file to the list that will be loaded when the suite is executed.
+ * @function
+ * @name Jasmine#addSpecFile
+ * @param {string} filePath The path to the file to be loaded.
+ */
 Jasmine.prototype.addSpecFile = function(filePath) {
   this.specFiles.push(filePath);
 };
 
+/**
+ * Add a custom reporter to the Jasmine environment.
+ * @function
+ * @name Jasmine#addReporter
+ * @param {Reporter} reporter The reporter to add
+ * @see custom_reporter
+ */
 Jasmine.prototype.addReporter = function(reporter) {
   this.env.addReporter(reporter);
   this.reportersCount++;
 };
 
+/**
+ * Clears all registered reporters.
+ * @function
+ * @name Jasmine#clearReporters
+ */
 Jasmine.prototype.clearReporters = function() {
   this.env.clearReporters();
   this.reportersCount = 0;
 };
 
+/**
+ * Provide a fallback reporter if no other reporters have been specified.
+ * @function
+ * @name Jasmine#provideFallbackReporter
+ * @param reporter The fallback reporter
+ * @see custom_reporter
+ */
 Jasmine.prototype.provideFallbackReporter = function(reporter) {
   this.env.provideFallbackReporter(reporter);
 };
@@ -82,6 +153,15 @@ Jasmine.prototype.configureDefaultReporter = function(options) {
   this.defaultReporterConfigured = true;
 };
 
+/**
+ * Add custom matchers for the current scope of specs.
+ *
+ * _Note:_ This is only callable from within a {@link beforeEach}, {@link it}, or {@link beforeAll}.
+ * @function
+ * @name Jasmine#addMatchers
+ * @param {Object} matchers - Keys from this object will be the new matcher names.
+ * @see custom_matcher
+ */
 Jasmine.prototype.addMatchers = function(matchers) {
   this.env.addMatchers(matchers);
 };
@@ -109,6 +189,12 @@ Jasmine.prototype.loadRequires = function() {
   });
 };
 
+/**
+ * Loads configuration from the specified file. The file can be a JSON file or
+ * any JS file that's loadable via require and provides a Jasmine config
+ * as its default export.
+ * @param configFilePath
+ */
 Jasmine.prototype.loadConfigFile = function(configFilePath) {
   try {
     var absoluteConfigFilePath = path.resolve(this.projectBaseDir, configFilePath || 'spec/support/jasmine.json');
@@ -119,6 +205,10 @@ Jasmine.prototype.loadConfigFile = function(configFilePath) {
   }
 };
 
+/**
+ * Loads configuration from the specified object.
+ * @param config
+ */
 Jasmine.prototype.loadConfig = function(config) {
   this.specDir = config.spec_dir || this.specDir;
 
@@ -216,14 +306,42 @@ function addFiles(kind) {
   };
 }
 
+/**
+ * Registers a callback that will be called when execution finishes.
+ *
+ * _Note_: Only one callback can be registered. The callback will be called
+ * after the suite has completed and the results have been finalized, but not
+ * necessarily before all of Jasmine's cleanup has finished.
+ *
+ * @deprecated Use the promise returned from {@link Jasmine#execute} instead.
+ * @param {function} onCompleteCallback
+ */
 Jasmine.prototype.onComplete = function(onCompleteCallback) {
   this.completionReporter.onComplete(onCompleteCallback);
 };
 
+/**
+ * Sets whether to cause specs to only have one expectation failure.
+ * @function
+ * @name Jasmine#stopSpecOnExpectationFailure
+ * @deprecated Use the oneFailurePerSped option with
+ * {@link Jasmine#loadConfig} or a config file instead.
+ * @param {boolean} value Whether to cause specs to only have one expectation
+ * failure
+ */
 Jasmine.prototype.stopSpecOnExpectationFailure = function(value) {
   this.env.configure({oneFailurePerSpec: value});
 };
 
+/**
+ * Sets whether to stop execution of the suite after the first spec failure.
+ * @function
+ * @name Jasmine#stopOnSpecFailure
+ * @deprecated Use the failFast option with {@link Jasmine#loadConfig} or a
+ * config file instead.
+ * @param {boolean} value Whether to stop execution of the suite after the
+ * first spec failure
+ */
 Jasmine.prototype.stopOnSpecFailure = function(value) {
   this.env.configure({failFast: value});
 };
@@ -267,6 +385,14 @@ function checkForJsFileImportSupport() {
   }
 }
 
+/**
+ * Runs the test suite.
+ * @param {Array.<string>} [files] Spec files to run instead of the previously
+ * configured set
+ * @param {string} [filterString] Regex used to filter specs. If specified, only
+ * specs with matching full names will be run.
+ * @return {Promise<void>} Promise that is resolved when the suite completes.
+ */
 Jasmine.prototype.execute = async function(files, filterString) {
   this.completionReporter.exitHandler = this.checkExit;