From 258252a7c1fb34a9a3711a941a0f95578c179b49 Mon Sep 17 00:00:00 2001
From: yorick <yorick@google.com>
Date: Thu, 17 Aug 2023 13:13:25 -0700
Subject: [PATCH] Marked Lists.newArrayList() and Lists.newLinkedList() as
 deprecated.

RELNOTES=Marked Lists.newArrayList() and Lists.newLinkedList() as deprecated.
PiperOrigin-RevId: 557915333
---
 .../src/com/google/common/collect/Lists.java  | 11 +++-
 .../src/com/google/common/collect/Maps.java   | 45 +++++++------
 .../src/com/google/common/collect/Queues.java | 66 ++++++++++++++++++-
 .../src/com/google/common/collect/Sets.java   | 24 ++++---
 .../common/util/concurrent/Atomics.java       | 10 +++
 .../src/com/google/common/collect/Lists.java  | 11 +++-
 guava/src/com/google/common/collect/Maps.java | 45 +++++++------
 .../src/com/google/common/collect/Queues.java | 66 ++++++++++++++++++-
 guava/src/com/google/common/collect/Sets.java | 24 ++++---
 .../common/util/concurrent/Atomics.java       | 10 +++
 10 files changed, 244 insertions(+), 68 deletions(-)

diff --git a/android/guava/src/com/google/common/collect/Lists.java b/android/guava/src/com/google/common/collect/Lists.java
index 304a5f57a32f..72309adc8a3d 100644
--- a/android/guava/src/com/google/common/collect/Lists.java
+++ b/android/guava/src/com/google/common/collect/Lists.java
@@ -77,13 +77,14 @@ private Lists() {}
    *
    * <p><b>Note:</b> if mutability is not required, use {@link ImmutableList#of()} instead.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
+   * @deprecated This method is unnecessary. Instead,
    * use the {@code ArrayList} {@linkplain ArrayList#ArrayList() constructor} directly, taking
    * advantage of <a
    * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
    * syntax</a>.
    */
   @SuppressWarnings("NonApiType") // acts as a direct substitute for a constructor call
+  @Deprecated
   public static <E extends @Nullable Object> ArrayList<E> newArrayList() {
     return new ArrayList<>();
   }
@@ -213,7 +214,7 @@ static int computeArrayListCapacity(int arraySize) {
    * outperform {@code LinkedList} except in certain rare and specific situations. Unless you have
    * spent a lot of time benchmarking your specific needs, use one of those instead.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
+   * @deprecated This method is unnecessary. Instead,
    * use the {@code LinkedList} {@linkplain LinkedList#LinkedList() constructor} directly, taking
    * advantage of <a
    * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
@@ -223,6 +224,7 @@ static int computeArrayListCapacity(int arraySize) {
     "NonApiType", // acts as a direct substitute for a constructor call
     "JdkObsolete", // We recommend against this method but need to keep it for compatibility.
   })
+  @Deprecated
   public static <E extends @Nullable Object> LinkedList<E> newLinkedList() {
     return new LinkedList<>();
   }
@@ -260,12 +262,17 @@ static int computeArrayListCapacity(int arraySize) {
    *
    * @return a new, empty {@code CopyOnWriteArrayList}
    * @since 12.0
+   * @deprecated This method is unnecessary. Instead, use the {@code CopyOnWriteArrayList} {@linkplain
+   *     CopyOnWriteArrayList#CopyOnWriteArrayList() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // CopyOnWriteArrayList
   @InlineMe(
       replacement = "new CopyOnWriteArrayList<>()",
       imports = {"java.util.concurrent.CopyOnWriteArrayList"})
+  @Deprecated
   public static <E extends @Nullable Object> CopyOnWriteArrayList<E> newCopyOnWriteArrayList() {
     return new CopyOnWriteArrayList<>();
   }
diff --git a/android/guava/src/com/google/common/collect/Maps.java b/android/guava/src/com/google/common/collect/Maps.java
index e7bc98145f66..30698b29af79 100644
--- a/android/guava/src/com/google/common/collect/Maps.java
+++ b/android/guava/src/com/google/common/collect/Maps.java
@@ -216,14 +216,14 @@ public static <K extends Enum<K>, V> ImmutableMap<K, V> immutableEnumMap(
    *
    * <p><b>Note:</b> if {@code K} is an {@code enum} type, use {@link #newEnumMap} instead.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code HashMap} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
-   *
    * @return a new, empty {@code HashMap}
+   * @deprecated This method is unnecessary. Instead, use the {@code HashMap} {@linkplain
+   *     HashMap#HashMap() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("NonApiType") // acts as a direct substitute for a constructor call
+  @Deprecated
   public static <K extends @Nullable Object, V extends @Nullable Object>
       HashMap<K, V> newHashMap() {
     return new HashMap<>();
@@ -299,14 +299,14 @@ static int capacity(int expectedSize) {
    *
    * <p><b>Note:</b> if mutability is not required, use {@link ImmutableMap#of()} instead.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code LinkedHashMap} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
-   *
    * @return a new, empty {@code LinkedHashMap}
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedHashMap} {@linkplain
+   *     LinkedHashMap#LinkedHashMap() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("NonApiType") // acts as a direct substitute for a constructor call
+  @Deprecated
   public static <K extends @Nullable Object, V extends @Nullable Object>
       LinkedHashMap<K, V> newLinkedHashMap() {
     return new LinkedHashMap<>();
@@ -353,13 +353,13 @@ LinkedHashMap<K, V> newLinkedHashMapWithExpectedSize(int expectedSize) {
   /**
    * Creates a new empty {@link ConcurrentHashMap} instance.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code ConcurrentHashMap} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
-   *
    * @since 3.0
+   * @deprecated This method is unnecessary. Instead, use the {@code ConcurrentHashMap} {@linkplain
+   *     ConcurrentHashMap#ConcurrentHashMap() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <K, V> ConcurrentMap<K, V> newConcurrentMap() {
     return new ConcurrentHashMap<>();
   }
@@ -438,7 +438,12 @@ TreeMap<K, V> newTreeMap(@Nullable Comparator<C> comparator) {
    *
    * @param type the key type for this map
    * @return a new, empty {@code EnumMap}
+   * @deprecated This method is unnecessary. Instead, use the {@code EnumMap} {@linkplain
+   *     EnumMap#EnumMap(Class) constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <K extends Enum<K>, V extends @Nullable Object> EnumMap<K, V> newEnumMap(
       Class<K> type) {
     return new EnumMap<>(checkNotNull(type));
@@ -465,13 +470,13 @@ TreeMap<K, V> newTreeMap(@Nullable Comparator<C> comparator) {
   /**
    * Creates an {@code IdentityHashMap} instance.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code IdentityHashMap} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
-   *
    * @return a new, empty {@code IdentityHashMap}
+   * @deprecated This method is unnecessary. Instead, use the {@code IdentityHashMap} {@linkplain
+   *     IdentityHashMap#IdentityHashMap() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <K extends @Nullable Object, V extends @Nullable Object>
       IdentityHashMap<K, V> newIdentityHashMap() {
     return new IdentityHashMap<>();
diff --git a/android/guava/src/com/google/common/collect/Queues.java b/android/guava/src/com/google/common/collect/Queues.java
index 374c09784aed..6cb72613e5a9 100644
--- a/android/guava/src/com/google/common/collect/Queues.java
+++ b/android/guava/src/com/google/common/collect/Queues.java
@@ -54,9 +54,15 @@ private Queues() {}
   /**
    * Creates an empty {@code ArrayBlockingQueue} with the given (fixed) capacity and nonfair access
    * policy.
+   *
+   * @deprecated This method is unnecessary. Instead, use the {@code ArrayBlockingQueue} {@linkplain
+   *     ArrayBlockingQueue#ArrayBlockingQueue(int) constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // ArrayBlockingQueue
+  @Deprecated
   public static <E> ArrayBlockingQueue<E> newArrayBlockingQueue(int capacity) {
     return new ArrayBlockingQueue<>(capacity);
   }
@@ -67,7 +73,12 @@ public static <E> ArrayBlockingQueue<E> newArrayBlockingQueue(int capacity) {
    * Creates an empty {@code ArrayDeque}.
    *
    * @since 12.0
+   * @deprecated This method is unnecessary. Instead, use the {@code ArrayDeque} {@linkplain
+   *     ArrayDeque#ArrayDeque() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <E> ArrayDeque<E> newArrayDeque() {
     return new ArrayDeque<>();
   }
@@ -89,9 +100,17 @@ public static <E> ArrayDeque<E> newArrayDeque(Iterable<? extends E> elements) {
 
   // ConcurrentLinkedQueue
 
-  /** Creates an empty {@code ConcurrentLinkedQueue}. */
+  /**
+   * Creates an empty {@code ConcurrentLinkedQueue}.
+   *
+   * @deprecated This method is unnecessary. Instead, use the {@code ConcurrentLinkedQueue} {@linkplain
+   *     ConcurrentLinkedQueue#ConcurrentLinkedQueue() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
+   */
   @J2ktIncompatible
   @GwtIncompatible // ConcurrentLinkedQueue
+  @Deprecated
   public static <E> ConcurrentLinkedQueue<E> newConcurrentLinkedQueue() {
     return new ConcurrentLinkedQueue<>();
   }
@@ -118,9 +137,14 @@ public static <E> ConcurrentLinkedQueue<E> newConcurrentLinkedQueue(
    * Creates an empty {@code LinkedBlockingDeque} with a capacity of {@link Integer#MAX_VALUE}.
    *
    * @since 12.0
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedBlockingDeque} {@linkplain
+   *     LinkedBlockingDeque#LinkedBlockingDeque() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // LinkedBlockingDeque
+  @Deprecated
   public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque() {
     return new LinkedBlockingDeque<>();
   }
@@ -130,9 +154,14 @@ public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque() {
    *
    * @throws IllegalArgumentException if {@code capacity} is less than 1
    * @since 12.0
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedBlockingDeque} {@linkplain
+   *     LinkedBlockingDeque#LinkedBlockingDeque(int) constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // LinkedBlockingDeque
+  @Deprecated
   public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque(int capacity) {
     return new LinkedBlockingDeque<>(capacity);
   }
@@ -157,9 +186,17 @@ public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque(Iterable<? exten
 
   // LinkedBlockingQueue
 
-  /** Creates an empty {@code LinkedBlockingQueue} with a capacity of {@link Integer#MAX_VALUE}. */
+  /**
+   * Creates an empty {@code LinkedBlockingQueue} with a capacity of {@link Integer#MAX_VALUE}.
+   *
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedBlockingQueue} {@linkplain
+   *     LinkedBlockingQueue#LinkedBlockingQueue() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
+   */
   @J2ktIncompatible
   @GwtIncompatible // LinkedBlockingQueue
+  @Deprecated
   public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue() {
     return new LinkedBlockingQueue<>();
   }
@@ -168,9 +205,14 @@ public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue() {
    * Creates an empty {@code LinkedBlockingQueue} with the given (fixed) capacity.
    *
    * @throws IllegalArgumentException if {@code capacity} is less than 1
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedBlockingQueue} {@linkplain
+   *     LinkedBlockingQueue#LinkedBlockingQueue(int) constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // LinkedBlockingQueue
+  @Deprecated
   public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue(int capacity) {
     return new LinkedBlockingQueue<>(capacity);
   }
@@ -204,10 +246,15 @@ public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue(Iterable<? exten
    *
    * @since 11.0 (but the bound of {@code E} was changed from {@code Object} to {@code Comparable}
    *     in 15.0)
+   * @deprecated This method is unnecessary. Instead, use the {@code PriorityBlockingQueue} {@linkplain
+   *     PriorityBlockingQueue#PriorityBlockingQueue() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("rawtypes") // https://github.com/google/guava/issues/989
   @J2ktIncompatible
   @GwtIncompatible // PriorityBlockingQueue
+  @Deprecated
   public static <E extends Comparable> PriorityBlockingQueue<E> newPriorityBlockingQueue() {
     return new PriorityBlockingQueue<>();
   }
@@ -242,8 +289,13 @@ public static <E extends Comparable> PriorityBlockingQueue<E> newPriorityBlockin
    *
    * @since 11.0 (but the bound of {@code E} was changed from {@code Object} to {@code Comparable}
    *     in 15.0)
+   * @deprecated This method is unnecessary. Instead, use the {@code PriorityQueue} {@linkplain
+   *     PriorityQueue#PriorityQueue() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("rawtypes") // https://github.com/google/guava/issues/989
+  @Deprecated
   public static <E extends Comparable> PriorityQueue<E> newPriorityQueue() {
     return new PriorityQueue<>();
   }
@@ -270,9 +322,17 @@ public static <E extends Comparable> PriorityQueue<E> newPriorityQueue(
 
   // SynchronousQueue
 
-  /** Creates an empty {@code SynchronousQueue} with nonfair access policy. */
+  /**
+   * Creates an empty {@code SynchronousQueue} with nonfair access policy.
+   *
+   * @deprecated This method is unnecessary. Instead, use the {@code SynchronousQueue} {@linkplain
+   *     SynchronousQueue#SynchronousQueue() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
+   */
   @J2ktIncompatible
   @GwtIncompatible // SynchronousQueue
+  @Deprecated
   public static <E> SynchronousQueue<E> newSynchronousQueue() {
     return new SynchronousQueue<>();
   }
diff --git a/android/guava/src/com/google/common/collect/Sets.java b/android/guava/src/com/google/common/collect/Sets.java
index 739f3358b976..6290aa8e6872 100644
--- a/android/guava/src/com/google/common/collect/Sets.java
+++ b/android/guava/src/com/google/common/collect/Sets.java
@@ -184,12 +184,13 @@ public static <E extends Enum<E>> EnumSet<E> newEnumSet(
    * using a {@code LinkedHashSet} instead, at the cost of increased memory footprint, to get
    * deterministic iteration behavior.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code HashSet} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
+   * @deprecated This method is unnecessary. Instead, use the {@code HashSet} {@linkplain
+   *     HashSet#HashSet() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("NonApiType") // acts as a direct substitute for a constructor call
+  @Deprecated
   public static <E extends @Nullable Object> HashSet<E> newHashSet() {
     return new HashSet<>();
   }
@@ -316,14 +317,14 @@ public static <E> Set<E> newConcurrentHashSet(Iterable<? extends E> elements) {
    *
    * <p><b>Note:</b> if mutability is not required, use {@link ImmutableSet#of()} instead.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code LinkedHashSet} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
-   *
    * @return a new, empty {@code LinkedHashSet}
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedHashSet} {@linkplain
+   *     LinkedHashSet#LinkedHashSet() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("NonApiType") // acts as a direct substitute for a constructor call
+  @Deprecated
   public static <E extends @Nullable Object> LinkedHashSet<E> newLinkedHashSet() {
     return new LinkedHashSet<>();
   }
@@ -472,9 +473,14 @@ public static <E extends Comparable> TreeSet<E> newTreeSet(Iterable<? extends E>
    *
    * @return a new, empty {@code CopyOnWriteArraySet}
    * @since 12.0
+   * @deprecated This method is unnecessary. Instead, use the {@code CopyOnWriteArraySet} {@linkplain
+   *     CopyOnWriteArraySet#CopyOnWriteArraySet() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // CopyOnWriteArraySet
+  @Deprecated
   public static <E extends @Nullable Object> CopyOnWriteArraySet<E> newCopyOnWriteArraySet() {
     return new CopyOnWriteArraySet<>();
   }
diff --git a/android/guava/src/com/google/common/util/concurrent/Atomics.java b/android/guava/src/com/google/common/util/concurrent/Atomics.java
index 99098cb96763..6f37dc859fc5 100644
--- a/android/guava/src/com/google/common/util/concurrent/Atomics.java
+++ b/android/guava/src/com/google/common/util/concurrent/Atomics.java
@@ -33,7 +33,12 @@ private Atomics() {}
    * Creates an {@code AtomicReference} instance with no initial value.
    *
    * @return a new {@code AtomicReference} with no initial value
+   * @deprecated This method is unnecessary. Instead, use the {@code AtomicReference} {@linkplain
+   *     AtomicReference#AtomicReference() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <V> AtomicReference<@Nullable V> newReference() {
     return new AtomicReference<>();
   }
@@ -43,7 +48,12 @@ private Atomics() {}
    *
    * @param initialValue the initial value
    * @return a new {@code AtomicReference} with the given initial value
+   * @deprecated This method is unnecessary. Instead, use the {@code AtomicReference} {@linkplain
+   *     AtomicReference#AtomicReference(Object) constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <V extends @Nullable Object> AtomicReference<V> newReference(
       @ParametricNullness V initialValue) {
     return new AtomicReference<>(initialValue);
diff --git a/guava/src/com/google/common/collect/Lists.java b/guava/src/com/google/common/collect/Lists.java
index ae79f5e659c1..d3c2ec610124 100644
--- a/guava/src/com/google/common/collect/Lists.java
+++ b/guava/src/com/google/common/collect/Lists.java
@@ -78,13 +78,14 @@ private Lists() {}
    *
    * <p><b>Note:</b> if mutability is not required, use {@link ImmutableList#of()} instead.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
+   * @deprecated This method is unnecessary. Instead,
    * use the {@code ArrayList} {@linkplain ArrayList#ArrayList() constructor} directly, taking
    * advantage of <a
    * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
    * syntax</a>.
    */
   @SuppressWarnings("NonApiType") // acts as a direct substitute for a constructor call
+  @Deprecated
   public static <E extends @Nullable Object> ArrayList<E> newArrayList() {
     return new ArrayList<>();
   }
@@ -214,7 +215,7 @@ static int computeArrayListCapacity(int arraySize) {
    * outperform {@code LinkedList} except in certain rare and specific situations. Unless you have
    * spent a lot of time benchmarking your specific needs, use one of those instead.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
+   * @deprecated This method is unnecessary. Instead,
    * use the {@code LinkedList} {@linkplain LinkedList#LinkedList() constructor} directly, taking
    * advantage of <a
    * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
@@ -224,6 +225,7 @@ static int computeArrayListCapacity(int arraySize) {
     "NonApiType", // acts as a direct substitute for a constructor call
     "JdkObsolete", // We recommend against this method but need to keep it for compatibility.
   })
+  @Deprecated
   public static <E extends @Nullable Object> LinkedList<E> newLinkedList() {
     return new LinkedList<>();
   }
@@ -261,12 +263,17 @@ static int computeArrayListCapacity(int arraySize) {
    *
    * @return a new, empty {@code CopyOnWriteArrayList}
    * @since 12.0
+   * @deprecated This method is unnecessary. Instead, use the {@code CopyOnWriteArrayList} {@linkplain
+   *     CopyOnWriteArrayList#CopyOnWriteArrayList() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // CopyOnWriteArrayList
   @InlineMe(
       replacement = "new CopyOnWriteArrayList<>()",
       imports = {"java.util.concurrent.CopyOnWriteArrayList"})
+  @Deprecated
   public static <E extends @Nullable Object> CopyOnWriteArrayList<E> newCopyOnWriteArrayList() {
     return new CopyOnWriteArrayList<>();
   }
diff --git a/guava/src/com/google/common/collect/Maps.java b/guava/src/com/google/common/collect/Maps.java
index bb8173481186..b9c91757c26c 100644
--- a/guava/src/com/google/common/collect/Maps.java
+++ b/guava/src/com/google/common/collect/Maps.java
@@ -219,14 +219,14 @@ public static <K extends Enum<K>, V> ImmutableMap<K, V> immutableEnumMap(
    *
    * <p><b>Note:</b> if {@code K} is an {@code enum} type, use {@link #newEnumMap} instead.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code HashMap} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
-   *
    * @return a new, empty {@code HashMap}
+   * @deprecated This method is unnecessary. Instead, use the {@code HashMap} {@linkplain
+   *     HashMap#HashMap() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("NonApiType") // acts as a direct substitute for a constructor call
+  @Deprecated
   public static <K extends @Nullable Object, V extends @Nullable Object>
       HashMap<K, V> newHashMap() {
     return new HashMap<>();
@@ -302,14 +302,14 @@ static int capacity(int expectedSize) {
    *
    * <p><b>Note:</b> if mutability is not required, use {@link ImmutableMap#of()} instead.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code LinkedHashMap} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
-   *
    * @return a new, empty {@code LinkedHashMap}
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedHashMap} {@linkplain
+   *     LinkedHashMap#LinkedHashMap() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("NonApiType") // acts as a direct substitute for a constructor call
+  @Deprecated
   public static <K extends @Nullable Object, V extends @Nullable Object>
       LinkedHashMap<K, V> newLinkedHashMap() {
     return new LinkedHashMap<>();
@@ -356,13 +356,13 @@ LinkedHashMap<K, V> newLinkedHashMapWithExpectedSize(int expectedSize) {
   /**
    * Creates a new empty {@link ConcurrentHashMap} instance.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code ConcurrentHashMap} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
-   *
    * @since 3.0
+   * @deprecated This method is unnecessary. Instead, use the {@code ConcurrentHashMap} {@linkplain
+   *     ConcurrentHashMap#ConcurrentHashMap() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <K, V> ConcurrentMap<K, V> newConcurrentMap() {
     return new ConcurrentHashMap<>();
   }
@@ -441,7 +441,12 @@ TreeMap<K, V> newTreeMap(@Nullable Comparator<C> comparator) {
    *
    * @param type the key type for this map
    * @return a new, empty {@code EnumMap}
+   * @deprecated This method is unnecessary. Instead, use the {@code EnumMap} {@linkplain
+   *     EnumMap#EnumMap(Class) constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <K extends Enum<K>, V extends @Nullable Object> EnumMap<K, V> newEnumMap(
       Class<K> type) {
     return new EnumMap<>(checkNotNull(type));
@@ -468,13 +473,13 @@ TreeMap<K, V> newTreeMap(@Nullable Comparator<C> comparator) {
   /**
    * Creates an {@code IdentityHashMap} instance.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code IdentityHashMap} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
-   *
    * @return a new, empty {@code IdentityHashMap}
+   * @deprecated This method is unnecessary. Instead, use the {@code IdentityHashMap} {@linkplain
+   *     IdentityHashMap#IdentityHashMap() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <K extends @Nullable Object, V extends @Nullable Object>
       IdentityHashMap<K, V> newIdentityHashMap() {
     return new IdentityHashMap<>();
diff --git a/guava/src/com/google/common/collect/Queues.java b/guava/src/com/google/common/collect/Queues.java
index 41feea89901b..c22b038f9345 100644
--- a/guava/src/com/google/common/collect/Queues.java
+++ b/guava/src/com/google/common/collect/Queues.java
@@ -54,9 +54,15 @@ private Queues() {}
   /**
    * Creates an empty {@code ArrayBlockingQueue} with the given (fixed) capacity and nonfair access
    * policy.
+   *
+   * @deprecated This method is unnecessary. Instead, use the {@code ArrayBlockingQueue} {@linkplain
+   *     ArrayBlockingQueue#ArrayBlockingQueue(int) constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // ArrayBlockingQueue
+  @Deprecated
   public static <E> ArrayBlockingQueue<E> newArrayBlockingQueue(int capacity) {
     return new ArrayBlockingQueue<>(capacity);
   }
@@ -67,7 +73,12 @@ public static <E> ArrayBlockingQueue<E> newArrayBlockingQueue(int capacity) {
    * Creates an empty {@code ArrayDeque}.
    *
    * @since 12.0
+   * @deprecated This method is unnecessary. Instead, use the {@code ArrayDeque} {@linkplain
+   *     ArrayDeque#ArrayDeque() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <E> ArrayDeque<E> newArrayDeque() {
     return new ArrayDeque<>();
   }
@@ -89,9 +100,17 @@ public static <E> ArrayDeque<E> newArrayDeque(Iterable<? extends E> elements) {
 
   // ConcurrentLinkedQueue
 
-  /** Creates an empty {@code ConcurrentLinkedQueue}. */
+  /**
+   * Creates an empty {@code ConcurrentLinkedQueue}.
+   *
+   * @deprecated This method is unnecessary. Instead, use the {@code ConcurrentLinkedQueue} {@linkplain
+   *     ConcurrentLinkedQueue#ConcurrentLinkedQueue() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
+   */
   @J2ktIncompatible
   @GwtIncompatible // ConcurrentLinkedQueue
+  @Deprecated
   public static <E> ConcurrentLinkedQueue<E> newConcurrentLinkedQueue() {
     return new ConcurrentLinkedQueue<>();
   }
@@ -118,9 +137,14 @@ public static <E> ConcurrentLinkedQueue<E> newConcurrentLinkedQueue(
    * Creates an empty {@code LinkedBlockingDeque} with a capacity of {@link Integer#MAX_VALUE}.
    *
    * @since 12.0
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedBlockingDeque} {@linkplain
+   *     LinkedBlockingDeque#LinkedBlockingDeque() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // LinkedBlockingDeque
+  @Deprecated
   public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque() {
     return new LinkedBlockingDeque<>();
   }
@@ -130,9 +154,14 @@ public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque() {
    *
    * @throws IllegalArgumentException if {@code capacity} is less than 1
    * @since 12.0
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedBlockingDeque} {@linkplain
+   *     LinkedBlockingDeque#LinkedBlockingDeque(int) constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // LinkedBlockingDeque
+  @Deprecated
   public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque(int capacity) {
     return new LinkedBlockingDeque<>(capacity);
   }
@@ -157,9 +186,17 @@ public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque(Iterable<? exten
 
   // LinkedBlockingQueue
 
-  /** Creates an empty {@code LinkedBlockingQueue} with a capacity of {@link Integer#MAX_VALUE}. */
+  /**
+   * Creates an empty {@code LinkedBlockingQueue} with a capacity of {@link Integer#MAX_VALUE}.
+   *
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedBlockingQueue} {@linkplain
+   *     LinkedBlockingQueue#LinkedBlockingQueue() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
+   */
   @J2ktIncompatible
   @GwtIncompatible // LinkedBlockingQueue
+  @Deprecated
   public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue() {
     return new LinkedBlockingQueue<>();
   }
@@ -168,9 +205,14 @@ public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue() {
    * Creates an empty {@code LinkedBlockingQueue} with the given (fixed) capacity.
    *
    * @throws IllegalArgumentException if {@code capacity} is less than 1
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedBlockingQueue} {@linkplain
+   *     LinkedBlockingQueue#LinkedBlockingQueue(int) constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // LinkedBlockingQueue
+  @Deprecated
   public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue(int capacity) {
     return new LinkedBlockingQueue<>(capacity);
   }
@@ -204,10 +246,15 @@ public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue(Iterable<? exten
    *
    * @since 11.0 (but the bound of {@code E} was changed from {@code Object} to {@code Comparable}
    *     in 15.0)
+   * @deprecated This method is unnecessary. Instead, use the {@code PriorityBlockingQueue} {@linkplain
+   *     PriorityBlockingQueue#PriorityBlockingQueue() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("rawtypes") // https://github.com/google/guava/issues/989
   @J2ktIncompatible
   @GwtIncompatible // PriorityBlockingQueue
+  @Deprecated
   public static <E extends Comparable> PriorityBlockingQueue<E> newPriorityBlockingQueue() {
     return new PriorityBlockingQueue<>();
   }
@@ -242,8 +289,13 @@ public static <E extends Comparable> PriorityBlockingQueue<E> newPriorityBlockin
    *
    * @since 11.0 (but the bound of {@code E} was changed from {@code Object} to {@code Comparable}
    *     in 15.0)
+   * @deprecated This method is unnecessary. Instead, use the {@code PriorityQueue} {@linkplain
+   *     PriorityQueue#PriorityQueue() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("rawtypes") // https://github.com/google/guava/issues/989
+  @Deprecated
   public static <E extends Comparable> PriorityQueue<E> newPriorityQueue() {
     return new PriorityQueue<>();
   }
@@ -270,9 +322,17 @@ public static <E extends Comparable> PriorityQueue<E> newPriorityQueue(
 
   // SynchronousQueue
 
-  /** Creates an empty {@code SynchronousQueue} with nonfair access policy. */
+  /**
+   * Creates an empty {@code SynchronousQueue} with nonfair access policy.
+   *
+   * @deprecated This method is unnecessary. Instead, use the {@code SynchronousQueue} {@linkplain
+   *     SynchronousQueue#SynchronousQueue() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
+   */
   @J2ktIncompatible
   @GwtIncompatible // SynchronousQueue
+  @Deprecated
   public static <E> SynchronousQueue<E> newSynchronousQueue() {
     return new SynchronousQueue<>();
   }
diff --git a/guava/src/com/google/common/collect/Sets.java b/guava/src/com/google/common/collect/Sets.java
index 7c7092f08fec..729b65b2b221 100644
--- a/guava/src/com/google/common/collect/Sets.java
+++ b/guava/src/com/google/common/collect/Sets.java
@@ -185,12 +185,13 @@ public static <E extends Enum<E>> EnumSet<E> newEnumSet(
    * using a {@code LinkedHashSet} instead, at the cost of increased memory footprint, to get
    * deterministic iteration behavior.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code HashSet} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
+   * @deprecated This method is unnecessary. Instead, use the {@code HashSet} {@linkplain
+   *     HashSet#HashSet() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("NonApiType") // acts as a direct substitute for a constructor call
+  @Deprecated
   public static <E extends @Nullable Object> HashSet<E> newHashSet() {
     return new HashSet<>();
   }
@@ -317,14 +318,14 @@ public static <E> Set<E> newConcurrentHashSet(Iterable<? extends E> elements) {
    *
    * <p><b>Note:</b> if mutability is not required, use {@link ImmutableSet#of()} instead.
    *
-   * <p><b>Note:</b> this method is now unnecessary and should be treated as deprecated. Instead,
-   * use the {@code LinkedHashSet} constructor directly, taking advantage of <a
-   * href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
-   * syntax</a>.
-   *
    * @return a new, empty {@code LinkedHashSet}
+   * @deprecated This method is unnecessary. Instead, use the {@code LinkedHashSet} {@linkplain
+   *     LinkedHashSet#LinkedHashSet() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @SuppressWarnings("NonApiType") // acts as a direct substitute for a constructor call
+  @Deprecated
   public static <E extends @Nullable Object> LinkedHashSet<E> newLinkedHashSet() {
     return new LinkedHashSet<>();
   }
@@ -473,9 +474,14 @@ public static <E extends Comparable> TreeSet<E> newTreeSet(Iterable<? extends E>
    *
    * @return a new, empty {@code CopyOnWriteArraySet}
    * @since 12.0
+   * @deprecated This method is unnecessary. Instead, use the {@code CopyOnWriteArraySet} {@linkplain
+   *     CopyOnWriteArraySet#CopyOnWriteArraySet() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
   @J2ktIncompatible
   @GwtIncompatible // CopyOnWriteArraySet
+  @Deprecated
   public static <E extends @Nullable Object> CopyOnWriteArraySet<E> newCopyOnWriteArraySet() {
     return new CopyOnWriteArraySet<>();
   }
diff --git a/guava/src/com/google/common/util/concurrent/Atomics.java b/guava/src/com/google/common/util/concurrent/Atomics.java
index 99098cb96763..6f37dc859fc5 100644
--- a/guava/src/com/google/common/util/concurrent/Atomics.java
+++ b/guava/src/com/google/common/util/concurrent/Atomics.java
@@ -33,7 +33,12 @@ private Atomics() {}
    * Creates an {@code AtomicReference} instance with no initial value.
    *
    * @return a new {@code AtomicReference} with no initial value
+   * @deprecated This method is unnecessary. Instead, use the {@code AtomicReference} {@linkplain
+   *     AtomicReference#AtomicReference() constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <V> AtomicReference<@Nullable V> newReference() {
     return new AtomicReference<>();
   }
@@ -43,7 +48,12 @@ private Atomics() {}
    *
    * @param initialValue the initial value
    * @return a new {@code AtomicReference} with the given initial value
+   * @deprecated This method is unnecessary. Instead, use the {@code AtomicReference} {@linkplain
+   *     AtomicReference#AtomicReference(Object) constructor} directly, taking advantage of <a
+   *     href="https://docs.oracle.com/javase/tutorial/java/generics/genTypeInference.html#type-inference-instantiation">"diamond"
+   *     syntax</a>.
    */
+  @Deprecated
   public static <V extends @Nullable Object> AtomicReference<V> newReference(
       @ParametricNullness V initialValue) {
     return new AtomicReference<>(initialValue);