From f4a5ebb427b1f2420ac45fb25c1f1a9066836f41 Mon Sep 17 00:00:00 2001 From: cpovirk Date: Tue, 17 Dec 2024 08:55:18 -0800 Subject: [PATCH] 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 --- .../google/common/truth/DoubleSubject.java | 4 ++-- .../google/common/truth/ExpectFailure.java | 21 ++++++++++--------- .../com/google/common/truth/FloatSubject.java | 4 ++-- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/core/src/main/java/com/google/common/truth/DoubleSubject.java b/core/src/main/java/com/google/common/truth/DoubleSubject.java index f1a87351f..14c2969bc 100644 --- a/core/src/main/java/com/google/common/truth/DoubleSubject.java +++ b/core/src/main/java/com/google/common/truth/DoubleSubject.java @@ -92,7 +92,7 @@ public int hashCode() { * {@link #isEqualTo}. * *

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}. * *

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. * *

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. * *

You can use a tolerance of {@code 0.0} to assert the exact non-equality of finite doubles, diff --git a/core/src/main/java/com/google/common/truth/ExpectFailure.java b/core/src/main/java/com/google/common/truth/ExpectFailure.java index 8a2443817..09d4a5bc8 100644 --- a/core/src/main/java/com/google/common/truth/ExpectFailure.java +++ b/core/src/main/java/com/google/common/truth/ExpectFailure.java @@ -47,7 +47,8 @@ * } * } * - * 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: * * 

  * {@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}.
    *
    * 
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.
    *
-   * 
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.
+   * 
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()}:
    *
    * 
{@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()}:
    *
    * 
{@code AssertionError failure = expectFailureAbout(myTypes(), whenTesting ->
    * whenTesting.that(myType).hasProperty());}
diff --git a/core/src/main/java/com/google/common/truth/FloatSubject.java b/core/src/main/java/com/google/common/truth/FloatSubject.java
index c5d661185..78e0b635a 100644
--- a/core/src/main/java/com/google/common/truth/FloatSubject.java
+++ b/core/src/main/java/com/google/common/truth/FloatSubject.java
@@ -100,7 +100,7 @@ public int hashCode() {
    * {@link #isEqualTo}.
    *
    * 
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}.
    *
    * 
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.
    *
    * 
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.
    *
    * 
You can use a tolerance of {@code 0.0f} to assert the exact non-equality of finite floats,