Merge branch '3.99' into 4.0

lib/jasmine-core/core.py

@@ -1,4 +1,33 @@
 import pkg_resources
+import os
+
+if 'SUPPRESS_JASMINE_DEPRECATION' not in os.environ:
+    print('DEPRECATION WARNING:\n' +
+        '\n' +
+        'The Jasmine packages for Python are deprecated. There will be no further\n' +
+        'releases after the end of the Jasmine 3.x series. We recommend migrating to the\n' +
+        'following options:\n' +
+        '\n' +
+        '* jasmine-browser-runner (<https://github.com/jasmine/jasmine-browser>,\n' +
+        '  `npm install jasmine-browser-runner`) to run specs in browsers, including\n' +
+        '  headless Chrome and Saucelabs. This is the most direct replacement for the\n' +
+        '  jasmine server` and `jasmine ci` commands provided by the `jasmine` Python\n' +
+        '  package.\n' +
+        '* The jasmine npm package (<https://github.com/jasmine/jasmine-npm>,\n' +
+        '  `npm install jasmine`) to run specs under Node.js.\n' +
+        '* The standalone distribution from the latest Jasmine release\n' +
+        '  <https://github.com/jasmine/jasmine/releases> to run specs in browsers with\n' +
+        '  no additional tools.\n' +
+        '* The jasmine-core npm package (`npm install jasmine-core`) if all you need is\n' +
+        '  the Jasmine assets. This is the direct equivalent of the jasmine-core Python\n' +
+        '  package.\n' +
+        '\n' +
+        'Except for the standalone distribution, all of the above are distributed through\n' +
+        'npm.\n' +
+    	 '\n' +
+    	 'To prevent this message from appearing, set the SUPPRESS_JASMINE_DEPRECATION\n' +
+		 'environment variable.\n')
+
 
 try:
     from collections import OrderedDict

lib/jasmine-core/jasmine.js

@@ -3525,7 +3525,29 @@ getJasmineRequireObj().Expectation = function(j$) {
   });
 
   /**
-   * Asynchronous matchers.
+   * Asynchronous matchers that operate on an actual value which is a promise,
+   * and return a promise.
+   *
+   * Note: Specs must await the result of each async matcher, return the
+   * promise returned by the matcher, or return a promise that's derived from
+   * the one returned by the matcher. Otherwise the matcher will not be
+   * evaluated before the spec completes.
+   *
+   * @example
+   * // Good
+   * await expectAsync(aPromise).toBeResolved();
+   * @example
+   * // Good
+   * return expectAsync(aPromise).toBeResolved();
+   * @example
+   * // Good
+   * return expectAsync(aPromise).toBeResolved()
+   *  .then(function() {
+   *    // more spec code
+   *  });
+   * @example
+   * // Bad
+   * expectAsync(aPromise).toBeResolved();
    * @namespace async-matchers
    */
   function AsyncExpectation(options) {
@@ -8018,6 +8040,7 @@ getJasmineRequireObj().Spy = function(j$) {
          * @property {object} object - `this` context for the invocation.
          * @property {number} invocationOrder - Order of the invocation.
          * @property {Array} args - The arguments passed for this invocation.
+         * @property returnValue - The value that was returned from this invocation.
          */
         var callData = {
           object: context,