Skip to content

Commit

Permalink
Truth Javadoc tweaks:
Browse files Browse the repository at this point in the history 
- Continue changing docs to say "Checks that..." instead of "Fails unless...." I'd mentioned this in cl/680668770 but not done it. See also the somewhat similar cl/178917870.
- Continue changing docs to say "value under test" instead of "subject" when referring to, well, the value under test. I'd done a little of this in cl/680668770.
- Fill in some boilerplate Javadoc for the other `assertThat` overloads. I'd commented upon this in b/368371914. This continues a path that I've been very gradually pursuing in cl/166715211, cl/246871754, and cl/633264611.

This CL started as an excuse to see whether cl/681051228 has fixed #1343, but then I realized that I don't actually need a separate CL to test that. (Contrast to the _Sonatype_ fix, which _does_ require another CL.) But hey, it's not a bad thing to do, anyway.

RELNOTES=n/a
PiperOrigin-RevId: 681066698
  • Loading branch information
@cpovirk
cpovirk authored and Google Java Core Libraries committed Oct 1, 2024
1 parent f1f4d14 commit c4192d3
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 22 deletions.
45 changes: 23 additions & 22 deletions core/src/main/java/com/google/common/truth/Subject.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -123,19 +123,19 @@ protected Subject(FailureMetadata metadata, @Nullable Object actual) {
this.typeDescriptionOverride = typeDescriptionOverride;
}

/** Fails if the subject is not null. */
/** Checks that the value under test is null. */
public void isNull() {
standardIsEqualTo(null);
}

/** Fails if the subject is null. */
/** Checks that the value under test is not null. */
public void isNotNull() {
standardIsNotEqualTo(null);
}

/**
* Fails if the subject is not equal to the given object. For the purposes of this comparison, two
* objects are equal if any of the following is true:
* Checks that the value under test is equal to the given object. For the purposes of this
* comparison, two objects are equal if any of the following is true:
*
* <ul>
* <li>they are equal according to {@link Objects#equal}
Expand Down Expand Up @@ -176,8 +176,8 @@ private void standardIsEqualTo(@Nullable Object expected) {
}

/**
* Fails if the subject is equal to the given object. The meaning of equality is the same as for
* the {@link #isEqualTo} method.
* Checks that the value under test is not equal to the given object. The meaning of equality is
* the same as for the {@link #isEqualTo} method.
*/
public void isNotEqualTo(@Nullable Object unexpected) {
standardIsNotEqualTo(unexpected);
Expand Down Expand Up @@ -262,7 +262,7 @@ private static long integralValue(Object o) {
}

/**
* Fails if the value under test is not the same instance as the given object.
* Checks that the value under test is the same instance as the given object.
*
* <p>This method considers {@code null} to be "the same instance as" {@code null} and not the
* same instance as anything else.
Expand All @@ -283,7 +283,7 @@ public final void isSameInstanceAs(@Nullable Object expected) {
}

/**
* Fails if the value under test is the same instance as the given object.
* Checks that the value under test is not the same instance as the given object.
*
* <p>This method considers {@code null} to be "the same instance as" {@code null} and not the
* same instance as anything else.
Expand All @@ -299,7 +299,7 @@ public final void isNotSameInstanceAs(@Nullable Object unexpected) {
}
}

/** Fails if the subject is not an instance of the given class. */
/** Checks that the value under test is an instance of the given class. */
public void isInstanceOf(Class<?> clazz) {
if (clazz == null) {
throw new NullPointerException("clazz");
Expand All @@ -325,7 +325,7 @@ public void isInstanceOf(Class<?> clazz) {
}
}

/** Fails if the subject is an instance of the given class. */
/** Checks that the value under test is not an instance of the given class. */
public void isNotInstanceOf(Class<?> clazz) {
if (clazz == null) {
throw new NullPointerException("clazz");
Expand Down Expand Up @@ -358,7 +358,7 @@ private static boolean isInstanceOfType(Object instance, Class<?> clazz) {
return Platform.isInstanceOfType(instance, clazz);
}

/** Fails unless the subject is equal to any element in the given iterable. */
/** Checks that the value under test is equal to any element in the given iterable. */
public void isIn(@Nullable Iterable<?> iterable) {
checkNotNull(iterable);
if (!contains(iterable, actual)) {
Expand All @@ -373,21 +373,21 @@ private static boolean contains(Iterable<?> haystack, @Nullable Object needle) {
return Iterables.contains(haystack, needle);
}

/** Fails unless the subject is equal to any of the given elements. */
/** Checks that the value under test is equal to any of the given elements. */
public void isAnyOf(
@Nullable Object first, @Nullable Object second, @Nullable Object @Nullable ... rest) {
isIn(accumulate(first, second, rest));
}

/** Fails if the subject is equal to any element in the given iterable. */
/** Checks that the value under test is not equal to any element in the given iterable. */
public void isNotIn(@Nullable Iterable<?> iterable) {
checkNotNull(iterable);
if (Iterables.contains(iterable, actual)) {
failWithActual("expected not to be any of", iterable);
}
}

/** Fails if the subject is equal to any of the given elements. */
/** Checks that the value under test is not equal to any of the given elements. */
public void isNoneOf(
@Nullable Object first, @Nullable Object second, @Nullable Object @Nullable ... rest) {
isNotIn(accumulate(first, second, rest));
Expand Down Expand Up @@ -782,7 +782,7 @@ final void fail(String check) {
* Assembles a failure message and passes such to the FailureStrategy
*
* @param verb the check being asserted
* @param other the value against which the subject is compared
* @param other the value against which the value under test is compared
* @deprecated Prefer to construct {@link Fact}-style methods, typically by using {@link
* #failWithActual(String, Object)}. However, if you want to preserve your exact failure
* message as a migration aid, you can inline this method (and then inline the resulting
Expand All @@ -797,7 +797,7 @@ final void fail(String verb, Object other) {
* Assembles a failure message and passes such to the FailureStrategy
*
* @param verb the check being asserted
* @param messageParts the expectations against which the subject is compared
* @param messageParts the expectations against which the value under test is compared
* @deprecated Prefer to construct {@link Fact}-style methods, typically by using {@link
* #failWithActual(Fact, Fact...)}. However, if you want to preserve your exact failure
* message as a migration aid, you can inline this method.
Expand Down Expand Up @@ -1011,9 +1011,9 @@ private void failEqualityCheckNoComparisonFailure(ComparisonResult difference, F
* Assembles a failure message and passes it to the FailureStrategy
*
* @param verb the check being asserted
* @param expected the expectations against which the subject is compared
* @param expected the expectations against which the value under test is compared
* @param failVerb the failure of the check being asserted
* @param actual the actual value the subject was compared against
* @param actual the actual value that the value under test was compared against
* @deprecated Prefer to construct {@link Fact}-style methods, typically by using {@link
* #failWithActual(Fact, Fact...)}. However, if you want to preserve your exact failure
* message as a migration aid, you can inline this method.
Expand All @@ -1032,12 +1032,12 @@ final void failWithBadResults(String verb, Object expected, String failVerb, Obj
}

/**
* Assembles a failure message with an alternative representation of the wrapped subject and
* passes it to the FailureStrategy
* Assembles a failure message with an alternative representation of the wrapped value under test
* and passes it to the FailureStrategy
*
* @param verb the check being asserted
* @param expected the expected value of the check
* @param actual the custom representation of the subject to be reported in the failure.
* @param actual the custom representation of the value under test to be reported in the failure.
* @deprecated Prefer to construct {@link Fact}-style methods, typically by using {@link
* #failWithoutActual(Fact, Fact...)}. However, if you want to preserve your exact failure
* message as a migration aid, you can inline this method.
Expand Down Expand Up @@ -1092,7 +1092,8 @@ final void failWithoutActual(Iterable<Fact> facts) {
}

/**
* Assembles a failure message without a given subject and passes it to the FailureStrategy
* Assembles a failure message without a given value under test and passes it to the
* FailureStrategy.
*
* @param check the check being asserted
* @deprecated Prefer to construct {@link Fact}-style methods, typically by using {@link
Expand Down
41 changes: 41 additions & 0 deletions core/src/main/java/com/google/common/truth/Truth.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -149,19 +149,23 @@ CustomSubjectBuilderT assertAbout(
return assert_().about(factory);
}

/** Begins an assertion about a {@link Comparable}. */
public static <ComparableT extends Comparable<?>> ComparableSubject<ComparableT> assertThat(
@Nullable ComparableT actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link BigDecimal}. */
public static BigDecimalSubject assertThat(@Nullable BigDecimal actual) {
return assert_().that(actual);
}

/** Begins an assertion about an {@link Object}. */
public static Subject assertThat(@Nullable Object actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link Class}. */
@GwtIncompatible("ClassSubject.java")
@J2ktIncompatible
public static ClassSubject assertThat(@Nullable Class<?> actual) {
Expand Down Expand Up @@ -189,94 +193,117 @@ public static ThrowableSubject assertThat(@Nullable Throwable actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link Long}. */
public static LongSubject assertThat(@Nullable Long actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link Double}. */
public static DoubleSubject assertThat(@Nullable Double actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link Float}. */
public static FloatSubject assertThat(@Nullable Float actual) {
return assert_().that(actual);
}

/** Begins an assertion about an {@link Integer}. */
public static IntegerSubject assertThat(@Nullable Integer actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link Boolean}. */
public static BooleanSubject assertThat(@Nullable Boolean actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link String}. */
public static StringSubject assertThat(@Nullable String actual) {
return assert_().that(actual);
}

/** Begins an assertion about an {@link Iterable}. */
public static IterableSubject assertThat(@Nullable Iterable<?> actual) {
return assert_().that(actual);
}

/** Begins an assertion about an {@link Object} array. */
@SuppressWarnings("AvoidObjectArrays")
public static <T extends @Nullable Object> ObjectArraySubject<T> assertThat(
T @Nullable [] actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link boolean} array. */
public static PrimitiveBooleanArraySubject assertThat(boolean @Nullable [] actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link short} array. */
public static PrimitiveShortArraySubject assertThat(short @Nullable [] actual) {
return assert_().that(actual);
}

/** Begins an assertion about an {@link int} array. */
public static PrimitiveIntArraySubject assertThat(int @Nullable [] actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link long} array. */
public static PrimitiveLongArraySubject assertThat(long @Nullable [] actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link byte} array. */
public static PrimitiveByteArraySubject assertThat(byte @Nullable [] actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link char} array. */
public static PrimitiveCharArraySubject assertThat(char @Nullable [] actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link float} array. */
public static PrimitiveFloatArraySubject assertThat(float @Nullable [] actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link double} array. */
public static PrimitiveDoubleArraySubject assertThat(double @Nullable [] actual) {
return assert_().that(actual);
}

/** Begins an assertion about a Guava {@link com.google.common.base.Optional}. */
public static GuavaOptionalSubject assertThat(
com.google.common.base.@Nullable Optional<?> actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link Map}. */
public static MapSubject assertThat(@Nullable Map<?, ?> actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link Multimap}. */
public static MultimapSubject assertThat(@Nullable Multimap<?, ?> actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link Multiset}. */
public static MultisetSubject assertThat(@Nullable Multiset<?> actual) {
return assert_().that(actual);
}

/** Begins an assertion about a {@link Table}. */
public static TableSubject assertThat(@Nullable Table<?, ?, ?> actual) {
return assert_().that(actual);
}

/**
* Begins an assertion about an {@link Optional}.
*
* @since 1.3.0 (present in {@link Truth8} since before 1.0)
*/
@SuppressWarnings({
Expand All @@ -288,6 +315,8 @@ public static OptionalSubject assertThat(@Nullable Optional<?> actual) {
}

/**
* Begins an assertion about an {@link OptionalInt}.
*
* @since 1.3.0 (present in {@link Truth8} since before 1.0)
*/
@SuppressWarnings("Java7ApiChecker") // no more dangerous than wherever the user got the Stream
Expand All @@ -296,6 +325,8 @@ public static OptionalIntSubject assertThat(@Nullable OptionalInt actual) {
}

/**
* Begins an assertion about an {@link OptionalLong}.
*
* @since 1.4.0 (present in {@link Truth8} since before 1.0)
*/
@SuppressWarnings("Java7ApiChecker") // no more dangerous than wherever the user got the Stream
Expand All @@ -304,6 +335,8 @@ public static OptionalLongSubject assertThat(@Nullable OptionalLong actual) {
}

/**
* Begins an assertion about an {@link OptionalDouble}.
*
* @since 1.4.0 (present in {@link Truth8} since before 1.0)
*/
@SuppressWarnings("Java7ApiChecker") // no more dangerous than wherever the user got the Stream
Expand All @@ -312,6 +345,8 @@ public static OptionalDoubleSubject assertThat(@Nullable OptionalDouble actual)
}

/**
* Begins an assertion about a {@link Stream}.
*
* @since 1.4.0 (present in {@link Truth8} since before 1.0)
*/
@SuppressWarnings("Java7ApiChecker") // no more dangerous than wherever the user got the Stream
Expand All @@ -320,6 +355,8 @@ public static StreamSubject assertThat(@Nullable Stream<?> actual) {
}

/**
* Begins an assertion about an {@link IntStream}.
*
* @since 1.4.0 (present in {@link Truth8} since before 1.0)
*/
@SuppressWarnings("Java7ApiChecker") // no more dangerous than wherever the user got the Stream
Expand All @@ -328,6 +365,8 @@ public static IntStreamSubject assertThat(@Nullable IntStream actual) {
}

/**
* Begins an assertion about a {@link LongStream}.
*
* @since 1.4.0 (present in {@link Truth8} since before 1.0)
*/
@SuppressWarnings("Java7ApiChecker") // no more dangerous than wherever the user got the Stream
Expand All @@ -338,6 +377,8 @@ public static LongStreamSubject assertThat(@Nullable LongStream actual) {
// TODO(b/64757353): Add support for DoubleStream?

/**
* Begins an assertion about a {@link Path}.
*
* @since 1.4.0 (present in {@link Truth8} since before 1.0)
*/
@GwtIncompatible
Expand Down

0 comments on commit c4192d3

Please sign in to comment.