From c9c4bc5b387d9f46ffe989e74e253a72e4c084d5 Mon Sep 17 00:00:00 2001 From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Date: Wed, 11 Mar 2026 17:47:56 -0700 Subject: [PATCH] Document that ImmutableMultimap creation APIs produce ImmutableListMultimap ImmutableMultimap.builder() and build() return ImmutableListMultimap, but this was undocumented. Users were confused about which concrete type they would get, especially since the class-level javadoc warns against using ImmutableMultimap directly (see #5888). Add javadoc to builder() and build() clarifying the concrete type and recommending the more explicit ImmutableListMultimap.builder() or ImmutableSetMultimap.builder() instead. --- .../src/com/google/common/collect/ImmutableMultimap.java | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/guava/src/com/google/common/collect/ImmutableMultimap.java b/guava/src/com/google/common/collect/ImmutableMultimap.java index 24a8a1b1fb35..feeb919cb433 100644 --- a/guava/src/com/google/common/collect/ImmutableMultimap.java +++ b/guava/src/com/google/common/collect/ImmutableMultimap.java @@ -125,6 +125,10 @@ public static ImmutableMultimap of( /** * Returns a new builder. The generated builder is equivalent to the builder created by the {@link * Builder} constructor. + * + *

The returned builder always builds an {@link ImmutableListMultimap}. For clarity and to + * avoid the pitfalls described in the {@linkplain ImmutableMultimap class documentation}, prefer + * {@link ImmutableListMultimap#builder} or {@link ImmutableSetMultimap#builder}. */ public static Builder builder() { return new Builder<>(); @@ -360,7 +364,10 @@ Builder combine(Builder other) { return this; } - /** Returns a newly-created immutable multimap. */ + /** + * Returns a newly-created immutable multimap. The returned multimap is an {@link + * ImmutableListMultimap}. + */ public ImmutableMultimap build() { if (builderMap == null) { return ImmutableListMultimap.of();