Updated jsdocs for Env#execute

lib/jasmine-core/jasmine.js

@@ -1808,23 +1808,25 @@ getJasmineRequireObj().Env = function(j$) {
      *
      * Both parameters are optional, but a completion callback is only valid as
      * the second parameter. To specify a completion callback but not a list of
-     * specs/suites to run, pass null or undefined as the first parameter.
+     * specs/suites to run, pass null or undefined as the first parameter. The
+     * completion callback is supported for backward compatibility. In most
+     * cases it will be more convenient to use the returned promise instead.
      *
      * execute should not be called more than once unless the env has been
      * configured with `{autoCleanClosures: false}`.
      *
-     * If the environment supports promises, execute will return a promise that
+     * execute returns a promise. The promise will be resolved to the same
-     * is resolved after the suite finishes executing. The promise will be
+     * {@link JasmineDoneInfo|overall result} that's passed to the reporter's
-     * resolved (not rejected) to the suite's overall status as long as the
+     * `jasmineDone` method, even if the suite did not pass. To determine
-     * suite runs to completion. To determine whether the suite passed, check
+     * whether the suite passed, check the value that the promise resolves to
-     * the value that the promise resolves to or use a {@link Reporter}.
+     * or use a {@link Reporter}.
      *
      * @name Env#execute
      * @since 2.0.0
      * @function
      * @param {(string[])=} runnablesToRun IDs of suites and/or specs to run
      * @param {Function=} onComplete Function that will be called after all specs have run
-     * @return {Promise<string>}
+     * @return {Promise<JasmineDoneInfo>}
      */
     this.execute = function(runnablesToRun, onComplete) {
       if (this._executedBefore) {

src/core/Env.js

@@ -667,23 +667,25 @@ getJasmineRequireObj().Env = function(j$) {
      *
      * Both parameters are optional, but a completion callback is only valid as
      * the second parameter. To specify a completion callback but not a list of
-     * specs/suites to run, pass null or undefined as the first parameter.
+     * specs/suites to run, pass null or undefined as the first parameter. The
+     * completion callback is supported for backward compatibility. In most
+     * cases it will be more convenient to use the returned promise instead.
      *
      * execute should not be called more than once unless the env has been
      * configured with `{autoCleanClosures: false}`.
      *
-     * If the environment supports promises, execute will return a promise that
+     * execute returns a promise. The promise will be resolved to the same
-     * is resolved after the suite finishes executing. The promise will be
+     * {@link JasmineDoneInfo|overall result} that's passed to a reporter's
-     * resolved (not rejected) to the suite's overall status as long as the
+     * `jasmineDone` method, even if the suite did not pass. To determine
-     * suite runs to completion. To determine whether the suite passed, check
+     * whether the suite passed, check the value that the promise resolves to
-     * the value that the promise resolves to or use a {@link Reporter}.
+     * or use a {@link Reporter}.
      *
      * @name Env#execute
      * @since 2.0.0
      * @function
      * @param {(string[])=} runnablesToRun IDs of suites and/or specs to run
      * @param {Function=} onComplete Function that will be called after all specs have run
-     * @return {Promise<string>}
+     * @return {Promise<JasmineDoneInfo>}
      */
     this.execute = function(runnablesToRun, onComplete) {
       if (this._executedBefore) {