Begin updating package-info for collect and also docs of some its…

… individual types. Most of this CL is about moving lists of implementations of `Foo` into the Javadoc for `Foo` itself, freeing up space in `package-info`. I also sorted the main collection types by usage. RELNOTES=n/a PiperOrigin-RevId: 541192589
google · Jun 17, 2023 · b88a774 · b88a774
1 parent efede00
commit b88a774
Show file tree

Hide file tree

Showing 14 changed files with 138 additions and 162 deletions.
diff --git a/android/guava/src/com/google/common/collect/BiMap.java b/android/guava/src/com/google/common/collect/BiMap.java
@@ -28,6 +28,15 @@
  * that of its keys. This constraint enables bimaps to support an "inverse view", which is another
  * bimap containing the same entries as this bimap but with reversed keys and values.
  *
+ * <h3>Implementations</h3>
+ *
+ * <ul>
+ *   <li>{@link ImmutableBiMap}
+ *   <li>{@link HashBiMap}
+ *   <li>{@link EnumBiMap}
+ *   <li>{@link EnumHashBiMap}
+ * </ul>
+ *
  * <p>See the Guava User Guide article on <a href=
  * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#bimap">{@code BiMap}</a>.
  *

diff --git a/android/guava/src/com/google/common/collect/ClassToInstanceMap.java b/android/guava/src/com/google/common/collect/ClassToInstanceMap.java
@@ -32,13 +32,20 @@
  * <p>Like any other {@code Map<Class, Object>}, this map may contain entries for primitive types,
  * and a primitive type and its corresponding wrapper type may map to different values.
  *
- * <p>See the Guava User Guide article on <a href=
- * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#classtoinstancemap">{@code
- * ClassToInstanceMap}</a>.
+ * <h3>Implementations</h3>
+ *
+ * <ul>
+ *   <li>{@link ImmutableClassToInstanceMap}
+ *   <li>{@link MutableClassToInstanceMap}
+ * </ul>
  *
  * <p>To map a generic type to an instance of that type, use {@link
  * com.google.common.reflect.TypeToInstanceMap} instead.
  *
+ * <p>See the Guava User Guide article on <a href=
+ * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#classtoinstancemap">{@code
+ * ClassToInstanceMap}</a>.
+ *
  * @param <B> the common supertype that all values will share. When in doubt, just use {@link
  *     Object}, or use {@code @Nullable Object} to allow null values.
  * @since 2.0

diff --git a/android/guava/src/com/google/common/collect/Multimap.java b/android/guava/src/com/google/common/collect/Multimap.java
@@ -132,13 +132,16 @@
  *
  * <h3>Implementations</h3>
  *
- * <p>As always, prefer the immutable implementations, {@link ImmutableListMultimap} and {@link
- * ImmutableSetMultimap}. General-purpose mutable implementations are listed above under "All Known
- * Implementing Classes". You can also create a <i>custom</i> multimap, backed by any {@code Map}
- * and {@link Collection} types, using the {@link Multimaps#newMultimap Multimaps.newMultimap}
- * family of methods. Finally, another popular way to obtain a multimap is using {@link
- * Multimaps#index Multimaps.index}. See the {@link Multimaps} class for these and other static
- * utilities related to multimaps.
+ * <ul>
+ *   <li>{@link ImmutableListMultimap}
+ *   <li>{@link ImmutableSetMultimap}
+ *   <li>Configure your own mutable multimap with {@link MultimapBuilder}
+ *   <li>{@link LinkedListMultimap} (for one unusual kind of mutable {@code Multimap})
+ * </ul>
+ *
+ * Guava contains a number of other multimap implementations, such as {@link ArrayListMultimap}. In
+ * new code, we recommend using {@link MultimapBuilder} instead: It provides better control of how
+ * keys and values are stored.
  *
  * <h3>Other Notes</h3>
  *

diff --git a/android/guava/src/com/google/common/collect/MultimapBuilder.java b/android/guava/src/com/google/common/collect/MultimapBuilder.java
@@ -37,17 +37,14 @@
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
- * A builder for a multimap implementation that allows customization of the backing map and value
- * collection implementations used in a particular multimap.
- *
- * <p>This can be used to easily configure multimap data structure implementations not provided
- * explicitly in {@code com.google.common.collect}, for example:
+ * An immutable builder for {@link Multimap} instances, letting you independently select the desired
+ * behaviors (for example, ordering) of the backing map and value-collections. Example:
  *
  * <pre>{@code
- * ListMultimap<String, Integer> treeListMultimap =
- *     MultimapBuilder.treeKeys().arrayListValues().build();
- * SetMultimap<Integer, MyEnum> hashEnumMultimap =
- *     MultimapBuilder.hashKeys().enumSetValues(MyEnum.class).build();
+ * ListMultimap<UserId, ErrorResponse> errorsByUser =
+ *     MultimapBuilder.linkedHashKeys().arrayListValues().build();
+ * SortedSetMultimap<String, Method> methodsForName =
+ *     MultimapBuilder.treeKeys().treeSetValues(this::compareMethods).build();
  * }</pre>
  *
  * <p>{@code MultimapBuilder} instances are immutable. Invoking a configuration method has no effect

diff --git a/android/guava/src/com/google/common/collect/Multiset.java b/android/guava/src/com/google/common/collect/Multiset.java
@@ -66,8 +66,17 @@
  * element (in a way that affects its {@link Object#equals} behavior) while it is contained in a
  * multiset. Undefined behavior and bugs will result.
  *
- * <p>Common implementations include {@link ImmutableMultiset}, {@link HashMultiset}, and {@link
- * ConcurrentHashMultiset}.
+ * <h3>Implementations</h3>
+ *
+ * <ul>
+ *   <li>{@link ImmutableMultiset}
+ *   <li>{@link ImmutableSortedMultiset}
+ *   <li>{@link HashMultiset}
+ *   <li>{@link LinkedHashMultiset}
+ *   <li>{@link TreeMultiset}
+ *   <li>{@link EnumMultiset}
+ *   <li>{@link ConcurrentHashMultiset}
+ * </ul>
  *
  * <p>If your values may be zero, negative, or outside the range of an int, you may wish to use
  * {@link com.google.common.util.concurrent.AtomicLongMap} instead. Note, however, that unlike

diff --git a/android/guava/src/com/google/common/collect/Table.java b/android/guava/src/com/google/common/collect/Table.java
@@ -45,6 +45,16 @@
  * not be modifiable. When modification isn't supported, those methods will throw an {@link
  * UnsupportedOperationException}.
  *
+ * <h3>Implementations</h3>
+ *
+ * <ul>
+ *   <li>{@link ImmutableTable}
+ *   <li>{@link HashBasedTable}
+ *   <li>{@link TreeBasedTable}
+ *   <li>{@link ArrayTable}
+ *   <li>{@link Tables#newCustomTable Tables.newCustomTable}
+ * </ul>
+ *
  * <p>See the Guava User Guide article on <a href=
  * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#table">{@code Table}</a>.
  *

diff --git a/android/guava/src/com/google/common/collect/package-info.java b/android/guava/src/com/google/common/collect/package-info.java
@@ -22,15 +22,6 @@
  * <h2>Collection Types</h2>
  *
  * <dl>
- *   <dt>{@link BiMap}
- *   <dd>An extension of {@link java.util.Map} that guarantees the uniqueness of its values as well
- *       as that of its keys. This is sometimes called an "invertible map," since the restriction on
- *       values enables it to support an {@linkplain BiMap#inverse inverse view} -- which is another
- *       instance of {@code BiMap}.
- *   <dt>{@link Multiset}
- *   <dd>An extension of {@link java.util.Collection} that may contain duplicate values like a
- *       {@link java.util.List}, yet has order-independent equality like a {@link java.util.Set}.
- *       One typical use for a multiset is to represent a histogram.
  *   <dt>{@link Multimap}
  *   <dd>A new type, which is similar to {@link java.util.Map}, but may contain multiple entries
  *       with the same key. Some behaviors of {@link Multimap} are left unspecified and are provided
@@ -50,16 +41,28 @@
  *   <dt>{@link SortedSetMultimap}
  *   <dd>An extension of {@link SetMultimap} for which the {@linkplain SortedSetMultimap#get
  *       collection values} associated with a given key is a {@link java.util.SortedSet}.
+ *   <dt>{@link BiMap}
+ *   <dd>An extension of {@link java.util.Map} that guarantees the uniqueness of its values as well
+ *       as that of its keys. This is sometimes called an "invertible map," since the restriction on
+ *       values enables it to support an {@linkplain BiMap#inverse inverse view} -- which is another
+ *       instance of {@code BiMap}.
  *   <dt>{@link Table}
  *   <dd>A new type, which is similar to {@link java.util.Map}, but which indexes its values by an
  *       ordered pair of keys, a row key and column key.
+ *   <dt>{@link Multiset}
+ *   <dd>An extension of {@link java.util.Collection} that may contain duplicate values like a
+ *       {@link java.util.List}, yet has order-independent equality like a {@link java.util.Set}.
+ *       One typical use for a multiset is to represent a histogram.
  *   <dt>{@link ClassToInstanceMap}
  *   <dd>An extension of {@link java.util.Map} that associates a raw type with an instance of that
  *       type.
  * </dl>
  *
  * <h2>Collection Implementations</h2>
  *
+ * To find implementations of one of our own collection types, like {@link Multimap}, see that
+ * interface's own documentation.
+ *
  * <h3>of {@link java.util.List}</h3>
  *
  * <ul>
@@ -79,57 +82,7 @@
  * <ul>
  *   <li>{@link ImmutableMap}
  *   <li>{@link ImmutableSortedMap}
- *   <li>{@link MapMaker}
- * </ul>
- *
- * <h3>of {@link BiMap}</h3>
- *
- * <ul>
- *   <li>{@link ImmutableBiMap}
- *   <li>{@link HashBiMap}
- *   <li>{@link EnumBiMap}
- *   <li>{@link EnumHashBiMap}
- * </ul>
- *
- * <h3>of {@link Multiset}</h3>
- *
- * <ul>
- *   <li>{@link ImmutableMultiset}
- *   <li>{@link ImmutableSortedMultiset}
- *   <li>{@link HashMultiset}
- *   <li>{@link LinkedHashMultiset}
- *   <li>{@link TreeMultiset}
- *   <li>{@link EnumMultiset}
- *   <li>{@link ConcurrentHashMultiset}
- * </ul>
- *
- * <h3>of {@link Multimap}</h3>
- *
- * <ul>
- *   <li>{@link ImmutableMultimap}
- *   <li>{@link ImmutableListMultimap}
- *   <li>{@link ImmutableSetMultimap}
- *   <li>{@link ArrayListMultimap}
- *   <li>{@link HashMultimap}
- *   <li>{@link TreeMultimap}
- *   <li>{@link LinkedHashMultimap}
- *   <li>{@link LinkedListMultimap}
- * </ul>
- *
- * <h3>of {@link Table}</h3>
- *
- * <ul>
- *   <li>{@link ImmutableTable}
- *   <li>{@link ArrayTable}
- *   <li>{@link HashBasedTable}
- *   <li>{@link TreeBasedTable}
- * </ul>
- *
- * <h3>of {@link ClassToInstanceMap}</h3>
- *
- * <ul>
- *   <li>{@link ImmutableClassToInstanceMap}
- *   <li>{@link MutableClassToInstanceMap}
+ *   <li>Configure your own map with weak keys or values with {@link MapMaker}
  * </ul>
  *
  * <h2>Classes of static utility methods</h2>

diff --git a/guava/src/com/google/common/collect/BiMap.java b/guava/src/com/google/common/collect/BiMap.java
@@ -28,6 +28,15 @@
  * that of its keys. This constraint enables bimaps to support an "inverse view", which is another
  * bimap containing the same entries as this bimap but with reversed keys and values.
  *
+ * <h3>Implementations</h3>
+ *
+ * <ul>
+ *   <li>{@link ImmutableBiMap}
+ *   <li>{@link HashBiMap}
+ *   <li>{@link EnumBiMap}
+ *   <li>{@link EnumHashBiMap}
+ * </ul>
+ *
  * <p>See the Guava User Guide article on <a href=
  * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#bimap">{@code BiMap}</a>.
  *

diff --git a/guava/src/com/google/common/collect/ClassToInstanceMap.java b/guava/src/com/google/common/collect/ClassToInstanceMap.java
@@ -32,13 +32,20 @@
  * <p>Like any other {@code Map<Class, Object>}, this map may contain entries for primitive types,
  * and a primitive type and its corresponding wrapper type may map to different values.
  *
- * <p>See the Guava User Guide article on <a href=
- * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#classtoinstancemap">{@code
- * ClassToInstanceMap}</a>.
+ * <h3>Implementations</h3>
+ *
+ * <ul>
+ *   <li>{@link ImmutableClassToInstanceMap}
+ *   <li>{@link MutableClassToInstanceMap}
+ * </ul>
  *
  * <p>To map a generic type to an instance of that type, use {@link
  * com.google.common.reflect.TypeToInstanceMap} instead.
  *
+ * <p>See the Guava User Guide article on <a href=
+ * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#classtoinstancemap">{@code
+ * ClassToInstanceMap}</a>.
+ *
  * @param <B> the common supertype that all values will share. When in doubt, just use {@link
  *     Object}, or use {@code @Nullable Object} to allow null values.
  * @since 2.0

diff --git a/guava/src/com/google/common/collect/Multimap.java b/guava/src/com/google/common/collect/Multimap.java
@@ -135,13 +135,16 @@
  *
  * <h3>Implementations</h3>
  *
- * <p>As always, prefer the immutable implementations, {@link ImmutableListMultimap} and {@link
- * ImmutableSetMultimap}. General-purpose mutable implementations are listed above under "All Known
- * Implementing Classes". You can also create a <i>custom</i> multimap, backed by any {@code Map}
- * and {@link Collection} types, using the {@link Multimaps#newMultimap Multimaps.newMultimap}
- * family of methods. Finally, another popular way to obtain a multimap is using {@link
- * Multimaps#index Multimaps.index}. See the {@link Multimaps} class for these and other static
- * utilities related to multimaps.
+ * <ul>
+ *   <li>{@link ImmutableListMultimap}
+ *   <li>{@link ImmutableSetMultimap}
+ *   <li>Configure your own mutable multimap with {@link MultimapBuilder}
+ *   <li>{@link LinkedListMultimap} (for one unusual kind of mutable {@code Multimap})
+ * </ul>
+ *
+ * Guava contains a number of other multimap implementations, such as {@link ArrayListMultimap}. In
+ * new code, we recommend using {@link MultimapBuilder} instead: It provides better control of how
+ * keys and values are stored.
  *
  * <h3>Other Notes</h3>
  *

diff --git a/guava/src/com/google/common/collect/MultimapBuilder.java b/guava/src/com/google/common/collect/MultimapBuilder.java
@@ -37,17 +37,14 @@
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
- * A builder for a multimap implementation that allows customization of the backing map and value
- * collection implementations used in a particular multimap.
- *
- * <p>This can be used to easily configure multimap data structure implementations not provided
- * explicitly in {@code com.google.common.collect}, for example:
+ * An immutable builder for {@link Multimap} instances, letting you independently select the desired
+ * behaviors (for example, ordering) of the backing map and value-collections. Example:
  *
  * <pre>{@code
- * ListMultimap<String, Integer> treeListMultimap =
- *     MultimapBuilder.treeKeys().arrayListValues().build();
- * SetMultimap<Integer, MyEnum> hashEnumMultimap =
- *     MultimapBuilder.hashKeys().enumSetValues(MyEnum.class).build();
+ * ListMultimap<UserId, ErrorResponse> errorsByUser =
+ *     MultimapBuilder.linkedHashKeys().arrayListValues().build();
+ * SortedSetMultimap<String, Method> methodsForName =
+ *     MultimapBuilder.treeKeys().treeSetValues(this::compareMethods).build();
  * }</pre>
  *
  * <p>{@code MultimapBuilder} instances are immutable. Invoking a configuration method has no effect

diff --git a/guava/src/com/google/common/collect/Multiset.java b/guava/src/com/google/common/collect/Multiset.java
@@ -71,8 +71,17 @@
  * element (in a way that affects its {@link Object#equals} behavior) while it is contained in a
  * multiset. Undefined behavior and bugs will result.
  *
- * <p>Common implementations include {@link ImmutableMultiset}, {@link HashMultiset}, and {@link
- * ConcurrentHashMultiset}.
+ * <h3>Implementations</h3>
+ *
+ * <ul>
+ *   <li>{@link ImmutableMultiset}
+ *   <li>{@link ImmutableSortedMultiset}
+ *   <li>{@link HashMultiset}
+ *   <li>{@link LinkedHashMultiset}
+ *   <li>{@link TreeMultiset}
+ *   <li>{@link EnumMultiset}
+ *   <li>{@link ConcurrentHashMultiset}
+ * </ul>
  *
  * <p>If your values may be zero, negative, or outside the range of an int, you may wish to use
  * {@link com.google.common.util.concurrent.AtomicLongMap} instead. Note, however, that unlike

diff --git a/guava/src/com/google/common/collect/Table.java b/guava/src/com/google/common/collect/Table.java
@@ -45,6 +45,16 @@
  * not be modifiable. When modification isn't supported, those methods will throw an {@link
  * UnsupportedOperationException}.
  *
+ * <h3>Implementations</h3>
+ *
+ * <ul>
+ *   <li>{@link ImmutableTable}
+ *   <li>{@link HashBasedTable}
+ *   <li>{@link TreeBasedTable}
+ *   <li>{@link ArrayTable}
+ *   <li>{@link Tables#newCustomTable Tables.newCustomTable}
+ * </ul>
+ *
  * <p>See the Guava User Guide article on <a href=
  * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#table">{@code Table}</a>.
  *