Update Javadoc for ExpectFailure:

- The `TestRule` approach has been a legacy approach for a while now.
- JUnit changed the name of its method from "`expectThrows`" to "`assertThrows`."
- We renamed some Truth SPI classes from "`*Verb`" to "`*SubjectBuilder`" long ago.

Also, fix a few `@code` usages that should have been `@link`, similar to in cl/698378812.

RELNOTES=n/a
PiperOrigin-RevId: 707120959

core/src/main/java/com/google/common/truth/DoubleSubject.java

@@ -92,7 +92,7 @@ public int hashCode() {
    * {@link #isEqualTo}.
    *
    * <p>The check will pass if both values are zero, even if one is {@code 0.0} and the other is
-   * {@code -0.0}. Use {@code #isEqualTo} to assert that a value is exactly {@code 0.0} or that it
+   * {@code -0.0}. Use {@link #isEqualTo} to assert that a value is exactly {@code 0.0} or that it
    * is exactly {@code -0.0}.
    *
    * <p>You can use a tolerance of {@code 0.0} to assert the exact equality of finite doubles, but
@@ -132,7 +132,7 @@ public void of(double expected) {
    * #isNotNaN}, or {@link #isNotEqualTo} for checks with other behaviours.
    *
    * <p>The check will fail if both values are zero, even if one is {@code 0.0} and the other is
-   * {@code -0.0}. Use {@code #isNotEqualTo} for a test which fails for a value of exactly zero with
+   * {@code -0.0}. Use {@link #isNotEqualTo} for a test which fails for a value of exactly zero with
    * one sign but passes for zero with the opposite sign.
    *
    * <p>You can use a tolerance of {@code 0.0} to assert the exact non-equality of finite doubles,

core/src/main/java/com/google/common/truth/ExpectFailure.java

@@ -47,7 +47,8 @@
  * }
  * }</pre>
  *
- * Or, if you can't use lambdas:
+ * {@link ExpectFailure} also supports a legacy approach, which we no longer recommend now that all
+ * Truth users can use lambdas. That approach is based on the JUnit {@code @Rule} system:
  *
  * <pre>
  * {@code @Rule public final ExpectFailure expectFailure = new ExpectFailure();}
@@ -78,8 +79,8 @@ public final class ExpectFailure implements Platform.JUnitTestRule {
   public ExpectFailure() {}
 
   /**
-   * Returns a test verb that expects the chained assertion to fail, and makes the failure available
-   * via {@link #getFailure}.
+   * Legacy method that returns a subject builder that expects the chained assertion to fail, and
+   * makes the failure available via {@link #getFailure}.
    *
    * <p>An instance of {@code ExpectFailure} supports only one {@code whenTesting} call per test
    * method. The static {@link #expectFailure} method, by contrast, does not have this limitation.
@@ -100,8 +101,8 @@ public StandardSubjectBuilder whenTesting() {
   /**
    * Enters rule context to be ready to capture failures.
    *
-   * <p>This should be rarely used directly, except if this class is as a long living object but not
-   * as a JUnit rule, like truth subject tests where for GWT compatible reasons.
+   * <p>This should be used only from framework code. This normally means from the {@link #apply}
+   * method below, but our tests call it directly under J2CL.
    */
   void enterRuleContext() {
     this.inRuleContext = true;
@@ -124,7 +125,7 @@ void ensureFailureCaught() {
     }
   }
 
-  /** Returns the captured failure, if one occurred. */
+  /** Legacy method that returns the failure captured by {@link #whenTesting}, if one occurred. */
   public AssertionError getFailure() {
     if (failure == null) {
       throw new AssertionError("ExpectFailure did not capture a failure.");
@@ -148,8 +149,8 @@ private void captureFailure(AssertionError captured) {
   }
 
   /**
-   * Static alternative that directly returns the triggered failure. This is intended to be used in
-   * Java 8+ tests similar to {@code expectThrows()}:
+   * Captures and returns the failure produced by the assertion in the provided callback, similar to
+   * {@code assertThrows()}:
    *
    * <p>{@code AssertionError failure = expectFailure(whenTesting ->
    * whenTesting.that(4).isNotEqualTo(4));}
@@ -163,8 +164,8 @@ public static AssertionError expectFailure(StandardSubjectBuilderCallback assert
   }
 
   /**
-   * Static alternative that directly returns the triggered failure. This is intended to be used in
-   * Java 8+ tests similar to {@code expectThrows()}:
+   * Captures and returns the failure produced by the assertion in the provided callback, similar to
+   * {@code assertThrows()}:
    *
    * <p>{@code AssertionError failure = expectFailureAbout(myTypes(), whenTesting ->
    * whenTesting.that(myType).hasProperty());}

core/src/main/java/com/google/common/truth/FloatSubject.java

@@ -100,7 +100,7 @@ public int hashCode() {
    * {@link #isEqualTo}.
    *
    * <p>The check will pass if both values are zero, even if one is {@code 0.0f} and the other is
-   * {@code -0.0f}. Use {@code #isEqualTo} to assert that a value is exactly {@code 0.0f} or that it
+   * {@code -0.0f}. Use {@link #isEqualTo} to assert that a value is exactly {@code 0.0f} or that it
    * is exactly {@code -0.0f}.
    *
    * <p>You can use a tolerance of {@code 0.0f} to assert the exact equality of finite floats, but
@@ -140,7 +140,7 @@ public void of(float expected) {
    * #isNotNaN}, or {@link #isNotEqualTo} for checks with other behaviours.
    *
    * <p>The check will fail if both values are zero, even if one is {@code 0.0f} and the other is
-   * {@code -0.0f}. Use {@code #isNotEqualTo} for a test which fails for a value of exactly zero
+   * {@code -0.0f}. Use {@link #isNotEqualTo} for a test which fails for a value of exactly zero
    * with one sign but passes for zero with the opposite sign.
    *
    * <p>You can use a tolerance of {@code 0.0f} to assert the exact non-equality of finite floats,