From b50df335cbb3357685b8e347656828b71d330b82 Mon Sep 17 00:00:00 2001
From: Google Java Core Libraries <java-team-github-bot@google.com>
Date: Tue, 25 Jun 2024 14:05:57 -0700
Subject: [PATCH] Suggest using streams instead of `Maps.toMap()`.

RELNOTES=n/a
PiperOrigin-RevId: 646599789
---
 .../guava/src/com/google/common/collect/Maps.java    | 12 ++++++++++++
 guava/src/com/google/common/collect/Maps.java        | 12 ++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/android/guava/src/com/google/common/collect/Maps.java b/android/guava/src/com/google/common/collect/Maps.java
index 5ba7ff2b2283..346fa2db6467 100644
--- a/android/guava/src/com/google/common/collect/Maps.java
+++ b/android/guava/src/com/google/common/collect/Maps.java
@@ -1216,6 +1216,18 @@ public NavigableSet<E> descendingSet() {
    * <p>If {@code keys} is a {@link Set}, a live view can be obtained instead of a copy using {@link
    * Maps#asMap(Set, Function)}.
    *
+   * <p><b>Note:</b> on Java 8+, it is usually better to use streams. For example:
+   *
+   * <pre>{@code
+   * import static com.google.common.collect.ImmutableMap.toImmutableMap;
+   * ...
+   * ImmutableMap<Color, String> colorNames =
+   *     allColors.stream().collect(toImmutableMap(c -> c, c -> c.toString()));
+   * }</pre>
+   *
+   * <p>Streams provide a more standard and flexible API and the lambdas make it clear what the keys
+   * and values in the map are.
+   *
    * @throws NullPointerException if any element of {@code keys} is {@code null}, or if {@code
    *     valueFunction} produces {@code null} for any key
    * @since 14.0
diff --git a/guava/src/com/google/common/collect/Maps.java b/guava/src/com/google/common/collect/Maps.java
index 2622db163a80..acacb119d03c 100644
--- a/guava/src/com/google/common/collect/Maps.java
+++ b/guava/src/com/google/common/collect/Maps.java
@@ -1246,6 +1246,18 @@ public NavigableSet<E> descendingSet() {
    * <p>If {@code keys} is a {@link Set}, a live view can be obtained instead of a copy using {@link
    * Maps#asMap(Set, Function)}.
    *
+   * <p><b>Note:</b> on Java 8+, it is usually better to use streams. For example:
+   *
+   * <pre>{@code
+   * import static com.google.common.collect.ImmutableMap.toImmutableMap;
+   * ...
+   * ImmutableMap<Color, String> colorNames =
+   *     allColors.stream().collect(toImmutableMap(c -> c, c -> c.toString()));
+   * }</pre>
+   *
+   * <p>Streams provide a more standard and flexible API and the lambdas make it clear what the keys
+   * and values in the map are.
+   *
    * @throws NullPointerException if any element of {@code keys} is {@code null}, or if {@code
    *     valueFunction} produces {@code null} for any key
    * @since 14.0