diff --git a/android/guava-testlib/src/com/google/common/testing/ClassSanityTester.java b/android/guava-testlib/src/com/google/common/testing/ClassSanityTester.java index cd8d5fa89cbc..2e88e562e5a9 100644 --- a/android/guava-testlib/src/com/google/common/testing/ClassSanityTester.java +++ b/android/guava-testlib/src/com/google/common/testing/ClassSanityTester.java @@ -116,6 +116,7 @@ public int compare(Invokable left, Invokable right) { private final ListMultimap, Object> distinctValues = ArrayListMultimap.create(); private final NullPointerTester nullPointerTester = new NullPointerTester(); + /** Constructs a new {@code ClassSanityTester}. */ public ClassSanityTester() { // TODO(benyu): bake these into ArbitraryInstances. setDefault(byte.class, (byte) 1); diff --git a/android/guava-testlib/src/com/google/common/testing/EquivalenceTester.java b/android/guava-testlib/src/com/google/common/testing/EquivalenceTester.java index 6fe8a4b2a25a..dc482c62f8aa 100644 --- a/android/guava-testlib/src/com/google/common/testing/EquivalenceTester.java +++ b/android/guava-testlib/src/com/google/common/testing/EquivalenceTester.java @@ -81,6 +81,10 @@ public EquivalenceTester addEquivalenceGroup(T first, T... rest) { return this; } + /** + * Adds a group of objects that are supposed to be equivalent to each other and not equivalent to + * objects in any other equivalence group added to this tester. + */ @CanIgnoreReturnValue public EquivalenceTester addEquivalenceGroup(Iterable group) { delegate.addRelatedGroup(group); diff --git a/android/guava-testlib/src/com/google/common/testing/ForwardingWrapperTester.java b/android/guava-testlib/src/com/google/common/testing/ForwardingWrapperTester.java index 57cf3523da2a..5d5b0cdc458d 100644 --- a/android/guava-testlib/src/com/google/common/testing/ForwardingWrapperTester.java +++ b/android/guava-testlib/src/com/google/common/testing/ForwardingWrapperTester.java @@ -241,5 +241,6 @@ public String toString() { } } + /** Constructs a new {@code ForwardingWrapperTester}. */ public ForwardingWrapperTester() {} } diff --git a/android/guava-testlib/src/com/google/common/testing/GcFinalization.java b/android/guava-testlib/src/com/google/common/testing/GcFinalization.java index c1da8c8c34a1..b76647da040b 100644 --- a/android/guava-testlib/src/com/google/common/testing/GcFinalization.java +++ b/android/guava-testlib/src/com/google/common/testing/GcFinalization.java @@ -251,6 +251,7 @@ private static void createUnreachableLatchFinalizer(CountDownLatch latch) { */ @DoNotMock("Implement with a lambda") public interface FinalizationPredicate { + /** Returns {@code true} if the finalization condition is met. */ boolean isDone(); } diff --git a/android/guava-testlib/src/com/google/common/testing/NullPointerTester.java b/android/guava-testlib/src/com/google/common/testing/NullPointerTester.java index 6b7191dca27d..df4552bbf707 100644 --- a/android/guava-testlib/src/com/google/common/testing/NullPointerTester.java +++ b/android/guava-testlib/src/com/google/common/testing/NullPointerTester.java @@ -85,6 +85,7 @@ public final class NullPointerTester { * NullPointerTester. But if you are a user who is reading this because this change caused you * trouble, please let us know: https://github.com/google/guava/issues/new */ + /** Constructs a new {@code NullPointerTester}. */ @IgnoreJRERequirement public NullPointerTester() { try { diff --git a/android/guava-testlib/src/com/google/common/testing/SloppyTearDown.java b/android/guava-testlib/src/com/google/common/testing/SloppyTearDown.java index 1790499ca801..6d2bdf0dd3a1 100644 --- a/android/guava-testlib/src/com/google/common/testing/SloppyTearDown.java +++ b/android/guava-testlib/src/com/google/common/testing/SloppyTearDown.java @@ -44,5 +44,6 @@ public final void tearDown() { } } + /** Performs the actual teardown. Exceptions thrown by this method will be caught and logged. */ public abstract void sloppyTearDown() throws Exception; } diff --git a/android/guava-testlib/src/com/google/common/testing/TearDownStack.java b/android/guava-testlib/src/com/google/common/testing/TearDownStack.java index 5dff3b86df38..098e7b9bd004 100644 --- a/android/guava-testlib/src/com/google/common/testing/TearDownStack.java +++ b/android/guava-testlib/src/com/google/common/testing/TearDownStack.java @@ -48,12 +48,24 @@ public class TearDownStack implements TearDownAccepter { @GuardedBy("lock") final Deque stack = new ArrayDeque<>(); + /* + * TODO(cpovirk): Rework the "suppress" terminology in this class for Java's "new" concept of + * "suppressed exceptions." At the moment, we use addSuppressed only if suppressThrows is *false*! + */ + private final boolean suppressThrows; + /** + * Constructs a new {@code TearDownStack} that does not suppress exceptions throw during teardown. + */ public TearDownStack() { this.suppressThrows = false; } + /** + * Constructs a new {@code TearDownStack}, specifying whether to suppress exceptions thrown during + * teardown. + */ public TearDownStack(boolean suppressThrows) { this.suppressThrows = suppressThrows; } diff --git a/android/guava-testlib/src/com/google/common/testing/TestLogHandler.java b/android/guava-testlib/src/com/google/common/testing/TestLogHandler.java index 9dd796872232..ba2039ffbb85 100644 --- a/android/guava-testlib/src/com/google/common/testing/TestLogHandler.java +++ b/android/guava-testlib/src/com/google/common/testing/TestLogHandler.java @@ -79,6 +79,7 @@ public void flush() {} @Override public void close() {} + /** Clears all stored log records. */ public void clear() { synchronized (lock) { list.clear(); diff --git a/android/guava/src/com/google/common/base/CommonMatcher.java b/android/guava/src/com/google/common/base/CommonMatcher.java index 6d14c6bc2630..6f7482d8c64c 100644 --- a/android/guava/src/com/google/common/base/CommonMatcher.java +++ b/android/guava/src/com/google/common/base/CommonMatcher.java @@ -23,15 +23,27 @@ */ @GwtCompatible abstract class CommonMatcher { + /** Returns {@code true} if the entire input region matches the pattern. */ public abstract boolean matches(); + /** Attempts to find the next subsequence of the input sequence that matches the pattern. */ public abstract boolean find(); + /** + * Resets this matcher and then attempts to find the next subsequence of the input sequence that + * matches the pattern, starting at the specified index. + */ public abstract boolean find(int index); + /** + * Replaces every subsequence of the input sequence that matches the pattern with the given + * replacement string. + */ public abstract String replaceAll(String replacement); + /** Returns the offset after the last character matched. */ public abstract int end(); + /** Returns the start index of the previous match. */ public abstract int start(); } diff --git a/android/guava/src/com/google/common/base/CommonPattern.java b/android/guava/src/com/google/common/base/CommonPattern.java index 6be5b01408aa..b8532ac1fdbe 100644 --- a/android/guava/src/com/google/common/base/CommonPattern.java +++ b/android/guava/src/com/google/common/base/CommonPattern.java @@ -23,10 +23,13 @@ */ @GwtCompatible abstract class CommonPattern { + /** Returns a {@link CommonMatcher} for the given input. */ public abstract CommonMatcher matcher(CharSequence t); + /** Returns the pattern string. */ public abstract String pattern(); + /** Returns the flags used to compile this pattern. */ public abstract int flags(); // Re-declare this as abstract to force subclasses to override. diff --git a/android/guava/src/com/google/common/cache/CacheLoader.java b/android/guava/src/com/google/common/cache/CacheLoader.java index 98999ca2c09d..e3404b930212 100644 --- a/android/guava/src/com/google/common/cache/CacheLoader.java +++ b/android/guava/src/com/google/common/cache/CacheLoader.java @@ -27,6 +27,7 @@ import java.io.Serializable; import java.util.Map; import java.util.concurrent.Executor; +import org.jspecify.annotations.Nullable; /** * Computes or retrieves values, based on a key, for use in populating a {@link LoadingCache}. @@ -243,7 +244,8 @@ public static final class UnsupportedLoadingOperationException * @since 11.0 */ public static final class InvalidCacheLoadException extends RuntimeException { - public InvalidCacheLoadException(String message) { + /** Constructs a new {@code InvalidCacheLoadException} with the specified detail message. */ + public InvalidCacheLoadException(@Nullable String message) { super(message); } } diff --git a/android/guava/src/com/google/common/cache/ForwardingCache.java b/android/guava/src/com/google/common/cache/ForwardingCache.java index 4913da2e814d..79b034893e51 100644 --- a/android/guava/src/com/google/common/cache/ForwardingCache.java +++ b/android/guava/src/com/google/common/cache/ForwardingCache.java @@ -135,6 +135,7 @@ public void cleanUp() { public abstract static class SimpleForwardingCache extends ForwardingCache { private final Cache delegate; + /** Constructor for use by subclasses. */ protected SimpleForwardingCache(Cache delegate) { this.delegate = Preconditions.checkNotNull(delegate); } diff --git a/android/guava/src/com/google/common/cache/ForwardingLoadingCache.java b/android/guava/src/com/google/common/cache/ForwardingLoadingCache.java index 395cd1401730..c06bd2e8a765 100644 --- a/android/guava/src/com/google/common/cache/ForwardingLoadingCache.java +++ b/android/guava/src/com/google/common/cache/ForwardingLoadingCache.java @@ -81,6 +81,7 @@ public abstract static class SimpleForwardingLoadingCache extends ForwardingLoadingCache { private final LoadingCache delegate; + /** Constructor for use by subclasses. */ protected SimpleForwardingLoadingCache(LoadingCache delegate) { this.delegate = Preconditions.checkNotNull(delegate); } diff --git a/android/guava/src/com/google/common/collect/ImmutableRangeMap.java b/android/guava/src/com/google/common/collect/ImmutableRangeMap.java index eb37d4ca8901..b6f549ac6d90 100644 --- a/android/guava/src/com/google/common/collect/ImmutableRangeMap.java +++ b/android/guava/src/com/google/common/collect/ImmutableRangeMap.java @@ -112,6 +112,7 @@ public static , V> Builder builder() { public static final class Builder, V> { private final List, V>> entries; + /** Constructs a new builder. */ public Builder() { this.entries = new ArrayList<>(); } diff --git a/android/guava/src/com/google/common/collect/ImmutableRangeSet.java b/android/guava/src/com/google/common/collect/ImmutableRangeSet.java index 5a0cf8a706a1..d083ae5fe604 100644 --- a/android/guava/src/com/google/common/collect/ImmutableRangeSet.java +++ b/android/guava/src/com/google/common/collect/ImmutableRangeSet.java @@ -772,6 +772,7 @@ public static > Builder builder() { public static class Builder> { private final List> ranges; + /** Constructs a new builder. */ public Builder() { this.ranges = new ArrayList<>(); } diff --git a/android/guava/src/com/google/common/collect/Interners.java b/android/guava/src/com/google/common/collect/Interners.java index 14e689eac876..cf33ff7af2d5 100644 --- a/android/guava/src/com/google/common/collect/Interners.java +++ b/android/guava/src/com/google/common/collect/Interners.java @@ -81,6 +81,7 @@ public InternerBuilder concurrencyLevel(int concurrencyLevel) { return this; } + /** Builds and returns a new interner. */ public Interner build() { if (!strong) { mapMaker.weakKeys(); diff --git a/android/guava/src/com/google/common/io/InsecureRecursiveDeleteException.java b/android/guava/src/com/google/common/io/InsecureRecursiveDeleteException.java index 87c132580f1f..c091468c0c45 100644 --- a/android/guava/src/com/google/common/io/InsecureRecursiveDeleteException.java +++ b/android/guava/src/com/google/common/io/InsecureRecursiveDeleteException.java @@ -42,6 +42,7 @@ @IgnoreJRERequirement public final class InsecureRecursiveDeleteException extends FileSystemException { + /** Constructs a new {@code InsecureRecursiveDeleteException} for the specified file. */ public InsecureRecursiveDeleteException(@Nullable String file) { super(file, null, "unable to guarantee security of recursive delete"); } diff --git a/android/guava/src/com/google/common/net/HttpHeaders.java b/android/guava/src/com/google/common/net/HttpHeaders.java index 9343b36bb0f2..5ff310d1fa96 100644 --- a/android/guava/src/com/google/common/net/HttpHeaders.java +++ b/android/guava/src/com/google/common/net/HttpHeaders.java @@ -192,13 +192,28 @@ private HttpHeaders() {} public static final class ReferrerPolicyValues { private ReferrerPolicyValues() {} + /** The {@code no-referrer} referrer policy. */ public static final String NO_REFERRER = "no-referrer"; + + /** The {@code no-referrer-when-downgrade} referrer policy. */ public static final String NO_REFFERER_WHEN_DOWNGRADE = "no-referrer-when-downgrade"; + + /** The {@code same-origin} referrer policy. */ public static final String SAME_ORIGIN = "same-origin"; + + /** The {@code origin} referrer policy. */ public static final String ORIGIN = "origin"; + + /** The {@code strict-origin} referrer policy. */ public static final String STRICT_ORIGIN = "strict-origin"; + + /** The {@code origin-when-cross-origin} referrer policy. */ public static final String ORIGIN_WHEN_CROSS_ORIGIN = "origin-when-cross-origin"; + + /** The {@code strict-origin-when-cross-origin} referrer policy. */ public static final String STRICT_ORIGIN_WHEN_CROSS_ORIGIN = "strict-origin-when-cross-origin"; + + /** The {@code unsafe-url} referrer policy. */ public static final String UNSAFE_URL = "unsafe-url"; } diff --git a/android/guava/src/com/google/common/primitives/UnsignedInteger.java b/android/guava/src/com/google/common/primitives/UnsignedInteger.java index 8400477e11ad..bb14169415ef 100644 --- a/android/guava/src/com/google/common/primitives/UnsignedInteger.java +++ b/android/guava/src/com/google/common/primitives/UnsignedInteger.java @@ -41,8 +41,13 @@ */ @GwtCompatible public final class UnsignedInteger extends Number implements Comparable { + /** An {@code UnsignedInteger} constant holding the value 0. */ public static final UnsignedInteger ZERO = fromIntBits(0); + + /** An {@code UnsignedInteger} constant holding the value 1. */ public static final UnsignedInteger ONE = fromIntBits(1); + + /** An {@code UnsignedInteger} constant holding the maximum value, 2^32 - 1. */ public static final UnsignedInteger MAX_VALUE = fromIntBits(-1); private final int value; diff --git a/android/guava/src/com/google/common/primitives/UnsignedLong.java b/android/guava/src/com/google/common/primitives/UnsignedLong.java index f729381bde52..0d74ac803abd 100644 --- a/android/guava/src/com/google/common/primitives/UnsignedLong.java +++ b/android/guava/src/com/google/common/primitives/UnsignedLong.java @@ -41,8 +41,13 @@ public final class UnsignedLong extends Number implements Comparable extends TypeCapture { final TypeVariable typeVariable; + /** Constructor for use by subclasses. */ protected TypeParameter() { Type type = capture(); checkArgument(type instanceof TypeVariable, "%s should be a type variable.", type); diff --git a/android/guava/src/com/google/common/reflect/TypeResolver.java b/android/guava/src/com/google/common/reflect/TypeResolver.java index 26b9598e6060..0064af6a74b9 100644 --- a/android/guava/src/com/google/common/reflect/TypeResolver.java +++ b/android/guava/src/com/google/common/reflect/TypeResolver.java @@ -59,6 +59,7 @@ public final class TypeResolver { private final TypeTable typeTable; + /** Constructs a new {@code TypeResolver} with no type mappings. */ public TypeResolver() { this.typeTable = new TypeTable(); } diff --git a/android/guava/src/com/google/common/util/concurrent/ForwardingFuture.java b/android/guava/src/com/google/common/util/concurrent/ForwardingFuture.java index 3d6f34f8e30b..70707f7ff132 100644 --- a/android/guava/src/com/google/common/util/concurrent/ForwardingFuture.java +++ b/android/guava/src/com/google/common/util/concurrent/ForwardingFuture.java @@ -94,6 +94,7 @@ public abstract static class SimpleForwardingFuture extends ForwardingFuture { private final Future delegate; + /** Constructor for use by subclasses. */ protected SimpleForwardingFuture(Future delegate) { this.delegate = Preconditions.checkNotNull(delegate); } diff --git a/android/guava/src/com/google/common/util/concurrent/ForwardingListenableFuture.java b/android/guava/src/com/google/common/util/concurrent/ForwardingListenableFuture.java index 7c605ae6f0d1..c5ac1d22ecbc 100644 --- a/android/guava/src/com/google/common/util/concurrent/ForwardingListenableFuture.java +++ b/android/guava/src/com/google/common/util/concurrent/ForwardingListenableFuture.java @@ -64,6 +64,7 @@ public abstract static class SimpleForwardingListenableFuture { private final ListenableFuture delegate; + /** Constructor for use by subclasses. */ protected SimpleForwardingListenableFuture(ListenableFuture delegate) { this.delegate = Preconditions.checkNotNull(delegate); } diff --git a/android/guava/src/com/google/common/util/concurrent/ListenerCallQueue.java b/android/guava/src/com/google/common/util/concurrent/ListenerCallQueue.java index b38ae5e6af62..1ec431d0439a 100644 --- a/android/guava/src/com/google/common/util/concurrent/ListenerCallQueue.java +++ b/android/guava/src/com/google/common/util/concurrent/ListenerCallQueue.java @@ -230,5 +230,6 @@ public void run() { } } + /** Constructs a new {@code ListenerCallQueue}. */ ListenerCallQueue() {} } diff --git a/android/guava/src/com/google/common/util/concurrent/UncheckedTimeoutException.java b/android/guava/src/com/google/common/util/concurrent/UncheckedTimeoutException.java index 375b712028ee..794ecc337815 100644 --- a/android/guava/src/com/google/common/util/concurrent/UncheckedTimeoutException.java +++ b/android/guava/src/com/google/common/util/concurrent/UncheckedTimeoutException.java @@ -27,16 +27,22 @@ @J2ktIncompatible @GwtIncompatible public class UncheckedTimeoutException extends RuntimeException { + /** Constructs a new {@code UncheckedTimeoutException} with {@code null} as its detail message. */ public UncheckedTimeoutException() {} + /** Constructs a new {@code UncheckedTimeoutException} with the specified detail message. */ public UncheckedTimeoutException(@Nullable String message) { super(message); } + /** Constructs a new {@code UncheckedTimeoutException} with the specified cause. */ public UncheckedTimeoutException(@Nullable Throwable cause) { super(cause); } + /** + * Constructs a new {@code UncheckedTimeoutException} with the specified detail message and cause. + */ public UncheckedTimeoutException(@Nullable String message, @Nullable Throwable cause) { super(message, cause); } diff --git a/android/guava/src/com/google/common/util/concurrent/WrappingExecutorService.java b/android/guava/src/com/google/common/util/concurrent/WrappingExecutorService.java index 5bb56f06ded6..bb849e96771c 100644 --- a/android/guava/src/com/google/common/util/concurrent/WrappingExecutorService.java +++ b/android/guava/src/com/google/common/util/concurrent/WrappingExecutorService.java @@ -48,6 +48,7 @@ abstract class WrappingExecutorService implements ExecutorService { private final ExecutorService delegate; + /** Constructor for use by subclasses. */ protected WrappingExecutorService(ExecutorService delegate) { this.delegate = checkNotNull(delegate); } diff --git a/android/guava/src/com/google/common/util/concurrent/WrappingScheduledExecutorService.java b/android/guava/src/com/google/common/util/concurrent/WrappingScheduledExecutorService.java index 4df26ddc6280..58ac81ce508e 100644 --- a/android/guava/src/com/google/common/util/concurrent/WrappingScheduledExecutorService.java +++ b/android/guava/src/com/google/common/util/concurrent/WrappingScheduledExecutorService.java @@ -36,6 +36,7 @@ abstract class WrappingScheduledExecutorService extends WrappingExecutorService implements ScheduledExecutorService { final ScheduledExecutorService delegate; + /** Constructor for use by subclasses. */ protected WrappingScheduledExecutorService(ScheduledExecutorService delegate) { super(delegate); this.delegate = delegate; diff --git a/guava-testlib/src/com/google/common/testing/ClassSanityTester.java b/guava-testlib/src/com/google/common/testing/ClassSanityTester.java index cd8d5fa89cbc..2e88e562e5a9 100644 --- a/guava-testlib/src/com/google/common/testing/ClassSanityTester.java +++ b/guava-testlib/src/com/google/common/testing/ClassSanityTester.java @@ -116,6 +116,7 @@ public int compare(Invokable left, Invokable right) { private final ListMultimap, Object> distinctValues = ArrayListMultimap.create(); private final NullPointerTester nullPointerTester = new NullPointerTester(); + /** Constructs a new {@code ClassSanityTester}. */ public ClassSanityTester() { // TODO(benyu): bake these into ArbitraryInstances. setDefault(byte.class, (byte) 1); diff --git a/guava-testlib/src/com/google/common/testing/EquivalenceTester.java b/guava-testlib/src/com/google/common/testing/EquivalenceTester.java index 6fe8a4b2a25a..dc482c62f8aa 100644 --- a/guava-testlib/src/com/google/common/testing/EquivalenceTester.java +++ b/guava-testlib/src/com/google/common/testing/EquivalenceTester.java @@ -81,6 +81,10 @@ public EquivalenceTester addEquivalenceGroup(T first, T... rest) { return this; } + /** + * Adds a group of objects that are supposed to be equivalent to each other and not equivalent to + * objects in any other equivalence group added to this tester. + */ @CanIgnoreReturnValue public EquivalenceTester addEquivalenceGroup(Iterable group) { delegate.addRelatedGroup(group); diff --git a/guava-testlib/src/com/google/common/testing/ForwardingWrapperTester.java b/guava-testlib/src/com/google/common/testing/ForwardingWrapperTester.java index 57cf3523da2a..5d5b0cdc458d 100644 --- a/guava-testlib/src/com/google/common/testing/ForwardingWrapperTester.java +++ b/guava-testlib/src/com/google/common/testing/ForwardingWrapperTester.java @@ -241,5 +241,6 @@ public String toString() { } } + /** Constructs a new {@code ForwardingWrapperTester}. */ public ForwardingWrapperTester() {} } diff --git a/guava-testlib/src/com/google/common/testing/GcFinalization.java b/guava-testlib/src/com/google/common/testing/GcFinalization.java index c1da8c8c34a1..b76647da040b 100644 --- a/guava-testlib/src/com/google/common/testing/GcFinalization.java +++ b/guava-testlib/src/com/google/common/testing/GcFinalization.java @@ -251,6 +251,7 @@ private static void createUnreachableLatchFinalizer(CountDownLatch latch) { */ @DoNotMock("Implement with a lambda") public interface FinalizationPredicate { + /** Returns {@code true} if the finalization condition is met. */ boolean isDone(); } diff --git a/guava-testlib/src/com/google/common/testing/NullPointerTester.java b/guava-testlib/src/com/google/common/testing/NullPointerTester.java index 1e404b5f4e4b..ecbaa2e38183 100644 --- a/guava-testlib/src/com/google/common/testing/NullPointerTester.java +++ b/guava-testlib/src/com/google/common/testing/NullPointerTester.java @@ -87,6 +87,7 @@ public final class NullPointerTester { * NullPointerTester. But if you are a user who is reading this because this change caused you * trouble, please let us know: https://github.com/google/guava/issues/new */ + /** Constructs a new {@code NullPointerTester}. */ @IgnoreJRERequirement public NullPointerTester() { try { diff --git a/guava-testlib/src/com/google/common/testing/SloppyTearDown.java b/guava-testlib/src/com/google/common/testing/SloppyTearDown.java index 1790499ca801..6d2bdf0dd3a1 100644 --- a/guava-testlib/src/com/google/common/testing/SloppyTearDown.java +++ b/guava-testlib/src/com/google/common/testing/SloppyTearDown.java @@ -44,5 +44,6 @@ public final void tearDown() { } } + /** Performs the actual teardown. Exceptions thrown by this method will be caught and logged. */ public abstract void sloppyTearDown() throws Exception; } diff --git a/guava-testlib/src/com/google/common/testing/TearDownStack.java b/guava-testlib/src/com/google/common/testing/TearDownStack.java index 5dff3b86df38..098e7b9bd004 100644 --- a/guava-testlib/src/com/google/common/testing/TearDownStack.java +++ b/guava-testlib/src/com/google/common/testing/TearDownStack.java @@ -48,12 +48,24 @@ public class TearDownStack implements TearDownAccepter { @GuardedBy("lock") final Deque stack = new ArrayDeque<>(); + /* + * TODO(cpovirk): Rework the "suppress" terminology in this class for Java's "new" concept of + * "suppressed exceptions." At the moment, we use addSuppressed only if suppressThrows is *false*! + */ + private final boolean suppressThrows; + /** + * Constructs a new {@code TearDownStack} that does not suppress exceptions throw during teardown. + */ public TearDownStack() { this.suppressThrows = false; } + /** + * Constructs a new {@code TearDownStack}, specifying whether to suppress exceptions thrown during + * teardown. + */ public TearDownStack(boolean suppressThrows) { this.suppressThrows = suppressThrows; } diff --git a/guava-testlib/src/com/google/common/testing/TestLogHandler.java b/guava-testlib/src/com/google/common/testing/TestLogHandler.java index 9dd796872232..ba2039ffbb85 100644 --- a/guava-testlib/src/com/google/common/testing/TestLogHandler.java +++ b/guava-testlib/src/com/google/common/testing/TestLogHandler.java @@ -79,6 +79,7 @@ public void flush() {} @Override public void close() {} + /** Clears all stored log records. */ public void clear() { synchronized (lock) { list.clear(); diff --git a/guava/src/com/google/common/base/CommonMatcher.java b/guava/src/com/google/common/base/CommonMatcher.java index 6d14c6bc2630..6f7482d8c64c 100644 --- a/guava/src/com/google/common/base/CommonMatcher.java +++ b/guava/src/com/google/common/base/CommonMatcher.java @@ -23,15 +23,27 @@ */ @GwtCompatible abstract class CommonMatcher { + /** Returns {@code true} if the entire input region matches the pattern. */ public abstract boolean matches(); + /** Attempts to find the next subsequence of the input sequence that matches the pattern. */ public abstract boolean find(); + /** + * Resets this matcher and then attempts to find the next subsequence of the input sequence that + * matches the pattern, starting at the specified index. + */ public abstract boolean find(int index); + /** + * Replaces every subsequence of the input sequence that matches the pattern with the given + * replacement string. + */ public abstract String replaceAll(String replacement); + /** Returns the offset after the last character matched. */ public abstract int end(); + /** Returns the start index of the previous match. */ public abstract int start(); } diff --git a/guava/src/com/google/common/base/CommonPattern.java b/guava/src/com/google/common/base/CommonPattern.java index 6be5b01408aa..b8532ac1fdbe 100644 --- a/guava/src/com/google/common/base/CommonPattern.java +++ b/guava/src/com/google/common/base/CommonPattern.java @@ -23,10 +23,13 @@ */ @GwtCompatible abstract class CommonPattern { + /** Returns a {@link CommonMatcher} for the given input. */ public abstract CommonMatcher matcher(CharSequence t); + /** Returns the pattern string. */ public abstract String pattern(); + /** Returns the flags used to compile this pattern. */ public abstract int flags(); // Re-declare this as abstract to force subclasses to override. diff --git a/guava/src/com/google/common/cache/CacheLoader.java b/guava/src/com/google/common/cache/CacheLoader.java index a096848acd7e..af9bba3fecd5 100644 --- a/guava/src/com/google/common/cache/CacheLoader.java +++ b/guava/src/com/google/common/cache/CacheLoader.java @@ -27,6 +27,7 @@ import java.io.Serializable; import java.util.Map; import java.util.concurrent.Executor; +import org.jspecify.annotations.Nullable; /** * Computes or retrieves values, based on a key, for use in populating a {@link LoadingCache}. @@ -242,7 +243,8 @@ public static final class UnsupportedLoadingOperationException * @since 11.0 */ public static final class InvalidCacheLoadException extends RuntimeException { - public InvalidCacheLoadException(String message) { + /** Constructs a new {@code InvalidCacheLoadException} with the specified detail message. */ + public InvalidCacheLoadException(@Nullable String message) { super(message); } } diff --git a/guava/src/com/google/common/cache/ForwardingCache.java b/guava/src/com/google/common/cache/ForwardingCache.java index 4913da2e814d..79b034893e51 100644 --- a/guava/src/com/google/common/cache/ForwardingCache.java +++ b/guava/src/com/google/common/cache/ForwardingCache.java @@ -135,6 +135,7 @@ public void cleanUp() { public abstract static class SimpleForwardingCache extends ForwardingCache { private final Cache delegate; + /** Constructor for use by subclasses. */ protected SimpleForwardingCache(Cache delegate) { this.delegate = Preconditions.checkNotNull(delegate); } diff --git a/guava/src/com/google/common/cache/ForwardingLoadingCache.java b/guava/src/com/google/common/cache/ForwardingLoadingCache.java index 395cd1401730..c06bd2e8a765 100644 --- a/guava/src/com/google/common/cache/ForwardingLoadingCache.java +++ b/guava/src/com/google/common/cache/ForwardingLoadingCache.java @@ -81,6 +81,7 @@ public abstract static class SimpleForwardingLoadingCache extends ForwardingLoadingCache { private final LoadingCache delegate; + /** Constructor for use by subclasses. */ protected SimpleForwardingLoadingCache(LoadingCache delegate) { this.delegate = Preconditions.checkNotNull(delegate); } diff --git a/guava/src/com/google/common/collect/ImmutableRangeMap.java b/guava/src/com/google/common/collect/ImmutableRangeMap.java index 2c6a057a1d08..514fe1b1cbf0 100644 --- a/guava/src/com/google/common/collect/ImmutableRangeMap.java +++ b/guava/src/com/google/common/collect/ImmutableRangeMap.java @@ -112,6 +112,7 @@ public static , V> Builder builder() { public static final class Builder, V> { private final List, V>> entries; + /** Constructs a new builder. */ public Builder() { this.entries = new ArrayList<>(); } diff --git a/guava/src/com/google/common/collect/ImmutableRangeSet.java b/guava/src/com/google/common/collect/ImmutableRangeSet.java index 97a1def318c9..9712b092ebf7 100644 --- a/guava/src/com/google/common/collect/ImmutableRangeSet.java +++ b/guava/src/com/google/common/collect/ImmutableRangeSet.java @@ -771,6 +771,7 @@ public static > Builder builder() { public static class Builder> { private final List> ranges; + /** Constructs a new builder. */ public Builder() { this.ranges = new ArrayList<>(); } diff --git a/guava/src/com/google/common/collect/ImmutableSet.java b/guava/src/com/google/common/collect/ImmutableSet.java index b64c2dcaf135..15552ae48a7b 100644 --- a/guava/src/com/google/common/collect/ImmutableSet.java +++ b/guava/src/com/google/common/collect/ImmutableSet.java @@ -421,6 +421,10 @@ public static class Builder extends ImmutableCollection.Builder { private @Nullable SetBuilderImpl impl; boolean forceCopy; + /** + * Creates a new builder. The returned builder is equivalent to the builder generated by {@link + * ImmutableSet#builder}. + */ public Builder() { this(0); } diff --git a/guava/src/com/google/common/collect/Interners.java b/guava/src/com/google/common/collect/Interners.java index 14e689eac876..cf33ff7af2d5 100644 --- a/guava/src/com/google/common/collect/Interners.java +++ b/guava/src/com/google/common/collect/Interners.java @@ -81,6 +81,7 @@ public InternerBuilder concurrencyLevel(int concurrencyLevel) { return this; } + /** Builds and returns a new interner. */ public Interner build() { if (!strong) { mapMaker.weakKeys(); diff --git a/guava/src/com/google/common/io/InsecureRecursiveDeleteException.java b/guava/src/com/google/common/io/InsecureRecursiveDeleteException.java index 148b24f3cb5a..e74daaa15523 100644 --- a/guava/src/com/google/common/io/InsecureRecursiveDeleteException.java +++ b/guava/src/com/google/common/io/InsecureRecursiveDeleteException.java @@ -40,6 +40,7 @@ @J2ObjCIncompatible // java.nio.file public final class InsecureRecursiveDeleteException extends FileSystemException { + /** Constructs a new {@code InsecureRecursiveDeleteException} for the specified file. */ public InsecureRecursiveDeleteException(@Nullable String file) { super(file, null, "unable to guarantee security of recursive delete"); } diff --git a/guava/src/com/google/common/net/HttpHeaders.java b/guava/src/com/google/common/net/HttpHeaders.java index 9343b36bb0f2..5ff310d1fa96 100644 --- a/guava/src/com/google/common/net/HttpHeaders.java +++ b/guava/src/com/google/common/net/HttpHeaders.java @@ -192,13 +192,28 @@ private HttpHeaders() {} public static final class ReferrerPolicyValues { private ReferrerPolicyValues() {} + /** The {@code no-referrer} referrer policy. */ public static final String NO_REFERRER = "no-referrer"; + + /** The {@code no-referrer-when-downgrade} referrer policy. */ public static final String NO_REFFERER_WHEN_DOWNGRADE = "no-referrer-when-downgrade"; + + /** The {@code same-origin} referrer policy. */ public static final String SAME_ORIGIN = "same-origin"; + + /** The {@code origin} referrer policy. */ public static final String ORIGIN = "origin"; + + /** The {@code strict-origin} referrer policy. */ public static final String STRICT_ORIGIN = "strict-origin"; + + /** The {@code origin-when-cross-origin} referrer policy. */ public static final String ORIGIN_WHEN_CROSS_ORIGIN = "origin-when-cross-origin"; + + /** The {@code strict-origin-when-cross-origin} referrer policy. */ public static final String STRICT_ORIGIN_WHEN_CROSS_ORIGIN = "strict-origin-when-cross-origin"; + + /** The {@code unsafe-url} referrer policy. */ public static final String UNSAFE_URL = "unsafe-url"; } diff --git a/guava/src/com/google/common/primitives/UnsignedInteger.java b/guava/src/com/google/common/primitives/UnsignedInteger.java index 8400477e11ad..bb14169415ef 100644 --- a/guava/src/com/google/common/primitives/UnsignedInteger.java +++ b/guava/src/com/google/common/primitives/UnsignedInteger.java @@ -41,8 +41,13 @@ */ @GwtCompatible public final class UnsignedInteger extends Number implements Comparable { + /** An {@code UnsignedInteger} constant holding the value 0. */ public static final UnsignedInteger ZERO = fromIntBits(0); + + /** An {@code UnsignedInteger} constant holding the value 1. */ public static final UnsignedInteger ONE = fromIntBits(1); + + /** An {@code UnsignedInteger} constant holding the maximum value, 2^32 - 1. */ public static final UnsignedInteger MAX_VALUE = fromIntBits(-1); private final int value; diff --git a/guava/src/com/google/common/primitives/UnsignedLong.java b/guava/src/com/google/common/primitives/UnsignedLong.java index f729381bde52..0d74ac803abd 100644 --- a/guava/src/com/google/common/primitives/UnsignedLong.java +++ b/guava/src/com/google/common/primitives/UnsignedLong.java @@ -41,8 +41,13 @@ public final class UnsignedLong extends Number implements Comparable extends TypeCapture { final TypeVariable typeVariable; + /** Constructor for use by subclasses. */ protected TypeParameter() { Type type = capture(); checkArgument(type instanceof TypeVariable, "%s should be a type variable.", type); diff --git a/guava/src/com/google/common/reflect/TypeResolver.java b/guava/src/com/google/common/reflect/TypeResolver.java index 26b9598e6060..0064af6a74b9 100644 --- a/guava/src/com/google/common/reflect/TypeResolver.java +++ b/guava/src/com/google/common/reflect/TypeResolver.java @@ -59,6 +59,7 @@ public final class TypeResolver { private final TypeTable typeTable; + /** Constructs a new {@code TypeResolver} with no type mappings. */ public TypeResolver() { this.typeTable = new TypeTable(); } diff --git a/guava/src/com/google/common/util/concurrent/ForwardingFuture.java b/guava/src/com/google/common/util/concurrent/ForwardingFuture.java index 3d6f34f8e30b..70707f7ff132 100644 --- a/guava/src/com/google/common/util/concurrent/ForwardingFuture.java +++ b/guava/src/com/google/common/util/concurrent/ForwardingFuture.java @@ -94,6 +94,7 @@ public abstract static class SimpleForwardingFuture extends ForwardingFuture { private final Future delegate; + /** Constructor for use by subclasses. */ protected SimpleForwardingFuture(Future delegate) { this.delegate = Preconditions.checkNotNull(delegate); } diff --git a/guava/src/com/google/common/util/concurrent/ForwardingListenableFuture.java b/guava/src/com/google/common/util/concurrent/ForwardingListenableFuture.java index 7c605ae6f0d1..c5ac1d22ecbc 100644 --- a/guava/src/com/google/common/util/concurrent/ForwardingListenableFuture.java +++ b/guava/src/com/google/common/util/concurrent/ForwardingListenableFuture.java @@ -64,6 +64,7 @@ public abstract static class SimpleForwardingListenableFuture { private final ListenableFuture delegate; + /** Constructor for use by subclasses. */ protected SimpleForwardingListenableFuture(ListenableFuture delegate) { this.delegate = Preconditions.checkNotNull(delegate); } diff --git a/guava/src/com/google/common/util/concurrent/ListenerCallQueue.java b/guava/src/com/google/common/util/concurrent/ListenerCallQueue.java index b38ae5e6af62..1ec431d0439a 100644 --- a/guava/src/com/google/common/util/concurrent/ListenerCallQueue.java +++ b/guava/src/com/google/common/util/concurrent/ListenerCallQueue.java @@ -230,5 +230,6 @@ public void run() { } } + /** Constructs a new {@code ListenerCallQueue}. */ ListenerCallQueue() {} } diff --git a/guava/src/com/google/common/util/concurrent/UncheckedTimeoutException.java b/guava/src/com/google/common/util/concurrent/UncheckedTimeoutException.java index 375b712028ee..794ecc337815 100644 --- a/guava/src/com/google/common/util/concurrent/UncheckedTimeoutException.java +++ b/guava/src/com/google/common/util/concurrent/UncheckedTimeoutException.java @@ -27,16 +27,22 @@ @J2ktIncompatible @GwtIncompatible public class UncheckedTimeoutException extends RuntimeException { + /** Constructs a new {@code UncheckedTimeoutException} with {@code null} as its detail message. */ public UncheckedTimeoutException() {} + /** Constructs a new {@code UncheckedTimeoutException} with the specified detail message. */ public UncheckedTimeoutException(@Nullable String message) { super(message); } + /** Constructs a new {@code UncheckedTimeoutException} with the specified cause. */ public UncheckedTimeoutException(@Nullable Throwable cause) { super(cause); } + /** + * Constructs a new {@code UncheckedTimeoutException} with the specified detail message and cause. + */ public UncheckedTimeoutException(@Nullable String message, @Nullable Throwable cause) { super(message, cause); } diff --git a/guava/src/com/google/common/util/concurrent/WrappingExecutorService.java b/guava/src/com/google/common/util/concurrent/WrappingExecutorService.java index 5bb56f06ded6..bb849e96771c 100644 --- a/guava/src/com/google/common/util/concurrent/WrappingExecutorService.java +++ b/guava/src/com/google/common/util/concurrent/WrappingExecutorService.java @@ -48,6 +48,7 @@ abstract class WrappingExecutorService implements ExecutorService { private final ExecutorService delegate; + /** Constructor for use by subclasses. */ protected WrappingExecutorService(ExecutorService delegate) { this.delegate = checkNotNull(delegate); } diff --git a/guava/src/com/google/common/util/concurrent/WrappingScheduledExecutorService.java b/guava/src/com/google/common/util/concurrent/WrappingScheduledExecutorService.java index 4df26ddc6280..58ac81ce508e 100644 --- a/guava/src/com/google/common/util/concurrent/WrappingScheduledExecutorService.java +++ b/guava/src/com/google/common/util/concurrent/WrappingScheduledExecutorService.java @@ -36,6 +36,7 @@ abstract class WrappingScheduledExecutorService extends WrappingExecutorService implements ScheduledExecutorService { final ScheduledExecutorService delegate; + /** Constructor for use by subclasses. */ protected WrappingScheduledExecutorService(ScheduledExecutorService delegate) { super(delegate); this.delegate = delegate;