Document that assertThrows allows exception subtypes (#3729)

To avoid confusion, the docs are now more explicit and point to 
`assertThrowsExactly` as an alternative.

Co-authored-by: Marc Philipp <[email protected]>

junit-jupiter-api/src/main/java/org/junit/jupiter/api/Assertions.java

@@ -3113,11 +3113,16 @@ public static <T extends Throwable> T assertThrowsExactly(Class<T> expectedType,
 	 * <em>Assert</em> that execution of the supplied {@code executable} throws
 	 * an exception of the {@code expectedType} and return the exception.
 	 *
-	 * <p>If no exception is thrown, or if an exception of a different type is
-	 * thrown, this method will fail.
+	 * <p>The assertion passes if the thrown exception type is the same as
+	 * {@code expectedType} or a subtype thereof. To check for the exact thrown
+	 * type use {@link #assertThrowsExactly(Class, Executable) assertThrowsExactly}.
+	 * If no exception is thrown, or if an exception of a different type is thrown,
+	 * this method will fail.
 	 *
 	 * <p>If you do not want to perform additional checks on the exception instance,
 	 * ignore the return value.
+	 *
+	 * @see #assertThrowsExactly(Class, Executable)
 	 */
 	public static <T extends Throwable> T assertThrows(Class<T> expectedType, Executable executable) {
 		return AssertThrows.assertThrows(expectedType, executable);
@@ -3127,8 +3132,11 @@ public static <T extends Throwable> T assertThrows(Class<T> expectedType, Execut
 	 * <em>Assert</em> that execution of the supplied {@code executable} throws
 	 * an exception of the {@code expectedType} and return the exception.
 	 *
-	 * <p>If no exception is thrown, or if an exception of a different type is
-	 * thrown, this method will fail.
+	 * <p>The assertion passes if the thrown exception type is the same as
+	 * {@code expectedType} or a subtype thereof. To check for the exact thrown
+	 * type use {@link #assertThrowsExactly(Class, Executable, String) assertThrowsExactly}.
+	 * If no exception is thrown, or if an exception of a different type is thrown,
+	 * this method will fail.
 	 *
 	 * <p>If you do not want to perform additional checks on the exception instance,
 	 * ignore the return value.
@@ -3138,6 +3146,8 @@ public static <T extends Throwable> T assertThrows(Class<T> expectedType, Execut
 	 * exception. To assert the expected message of the thrown exception, you must
 	 * use a separate, subsequent assertion against the exception returned from
 	 * this method.
+	 *
+	 * @see #assertThrowsExactly(Class, Executable, String)
 	 */
 	public static <T extends Throwable> T assertThrows(Class<T> expectedType, Executable executable, String message) {
 		return AssertThrows.assertThrows(expectedType, executable, message);
@@ -3147,8 +3157,11 @@ public static <T extends Throwable> T assertThrows(Class<T> expectedType, Execut
 	 * <em>Assert</em> that execution of the supplied {@code executable} throws
 	 * an exception of the {@code expectedType} and return the exception.
 	 *
-	 * <p>If no exception is thrown, or if an exception of a different type is
-	 * thrown, this method will fail.
+	 * <p>The assertion passes if the thrown exception type is the same as
+	 * {@code expectedType} or a subtype thereof. To check for the exact thrown
+	 * type use {@link #assertThrowsExactly(Class, Executable, Supplier) assertThrowsExactly}.
+	 * If no exception is thrown, or if an exception of a different type is thrown,
+	 * this method will fail.
 	 *
 	 * <p>If necessary, the failure message will be retrieved lazily from the
 	 * supplied {@code messageSupplier}. Note that the failure message is
@@ -3159,6 +3172,8 @@ public static <T extends Throwable> T assertThrows(Class<T> expectedType, Execut
 	 *
 	 * <p>If you do not want to perform additional checks on the exception instance,
 	 * ignore the return value.
+	 *
+	 * @see #assertThrowsExactly(Class, Executable, Supplier)
 	 */
 	public static <T extends Throwable> T assertThrows(Class<T> expectedType, Executable executable,
 			Supplier<String> messageSupplier) {