Extracted the predicate version of toThrowError into its own matcher

This simplifies the signature of each matcher to something that jsdoc
can actually handle.

[Finishes #20622765]

src/core/matchers/requireMatchers.js

@@ -23,7 +23,8 @@ getJasmineRequireObj().requireMatchers = function(jRequire, j$) {
       'toHaveBeenCalledWith',
       'toMatch',
       'toThrow',
-      'toThrowError'
+      'toThrowError',
+      'toThrowMatching',
     ],
     matchers = {};
 

src/core/matchers/toThrowError.js

@@ -56,8 +56,6 @@ getJasmineRequireObj().toThrowError = function(j$) {
 
         if (isAnErrorType(arguments[1])) {
           return exactMatcher(null, arguments[1]);
-        } else if (j$.isFunction_(arguments[1])) {
-          return predicateMatcher(arguments[1]);
         } else {
           return exactMatcher(arguments[1], null);
         }
@@ -74,30 +72,12 @@ getJasmineRequireObj().toThrowError = function(j$) {
       };
     }
 
-    function predicateMatcher(predicate) {
-      return {
-        match: function(thrown) {
-          if (predicate(thrown)) {
-            return pass(function() {
-              return 'Expected function not to throw an exception matching a predicate.';
-            });
-          } else {
-            return fail(function() {
-              return 'Expected function to throw an exception matching a predicate, ' +
-                'but it threw ' + j$.fnNameFor(thrown.constructor) + ' with message ' +
-                j$.pp(thrown.message) + '.';
-            });
-          }
-        }
-      };
-    }
-
     function exactMatcher(expected, errorType) {
       if (expected && !isStringOrRegExp(expected)) {
         if (errorType) {
           throw new Error(getErrorMsg('Expected error message is not a string or RegExp.'));
         } else {
-          throw new Error(getErrorMsg('Expected is not an Error, string, RegExp, or Function.'));
+          throw new Error(getErrorMsg('Expected is not an Error, string, or RegExp.'));
         }
       }
 

src/core/matchers/toThrowMatching.js

@@ -0,0 +1,68 @@
+getJasmineRequireObj().toThrowMatching = function(j$) {
+  var usageError =  j$.formatErrorMsg('<toThrowMatching>', 'expect(function() {<expectation>}).toThrowMatching(<Predicate>)');
+
+  /**
+   * {@link expect} a function to `throw` something matching a predicate.
+   * @function
+   * @name matchers#toThrowMatching
+   * @param {Function} predicate - A function that takes the thrown exception as its parameter and returns true if it matches.
+   * @example
+   * expect(function() { throw new Error('nope'); }).toThrowMatching(function(thrown) { return thrown.message === 'nope'; });
+   */
+  function toThrowMatching() {
+    return {
+      compare: function(actual, predicate) {
+        var thrown;
+
+        if (typeof actual !== 'function') {
+          throw new Error(usageError('Actual is not a Function'));
+        }
+
+        if (typeof predicate !== 'function') {
+          throw new Error(usageError('Predicate is not a Function'));
+        }
+
+        try {
+          actual();
+          return fail('Expected function to throw an exception.');
+        } catch (e) {
+          thrown = e;
+        }
+
+        if (predicate(thrown)) {
+          return pass('Expected function not to throw an exception matching a predicate.');
+        } else {
+            return fail(function() {
+              return 'Expected function to throw an exception matching a predicate, ' +
+                'but it threw ' + thrownDescription(thrown) + '.';
+            });
+        }
+      }
+    };
+  }
+
+  function thrownDescription(thrown) {
+    if (thrown && thrown.constructor) {
+      return j$.fnNameFor(thrown.constructor) + ' with message ' +
+        j$.pp(thrown.message);
+    } else {
+      return j$.pp(thrown);
+    }
+  }
+
+  function pass(message) {
+    return {
+      pass: true,
+      message: message
+    };
+  }
+
+  function fail(message) {
+    return {
+      pass: false,
+      message: message
+    };
+  }
+
+  return toThrowMatching;
+};