Add some classes to package-info for primitives and util.concurrent.

cpovirk · Google Java Core Libraries · commit 641d9e682be2 · 2023-06-26T14:13:41.000-07:00
(Also, mention `FluentFuture` inside `ListenableFuture`.)

I also re-ordered some sections. There is an argument that the `primitives` static utilities still belong above the value types, but it depends on how you weigh total usages for the group of classes vs. usage of individual popular classes, how you adjust for utilities available in newer versions of Java, and how much we want to be prescriptive in suggesting things. I put some weight on "value types are a good thing."

RELNOTES=n/a
PiperOrigin-RevId: 543537713
diff --git a/android/guava/src/com/google/common/primitives/package-info.java b/android/guava/src/com/google/common/primitives/package-info.java
@@ -14,7 +14,7 @@
 
 /**
  * Static utilities for the eight primitive types and {@code void}, and value types for treating
- * them as unsigned.
+ * them as unsigned or storing them in immutable arrays.
  *
  * <p>This package is a part of the open-source <a href="https://github.com/google/guava">Guava</a>
  * library.
@@ -24,10 +24,14 @@
  *
  * <h2>Contents</h2>
  *
- * <h3>General static utilities</h3>
+ * <h3>Value types</h3>
  *
  * <ul>
- *   <li>{@link Primitives}
+ *   <li>{@link ImmutableDoubleArray}
+ *   <li>{@link ImmutableIntArray}
+ *   <li>{@link ImmutableLongrray}
+ *   <li>{@link UnsignedInteger}
+ *   <li>{@link UnsignedLong}
  * </ul>
  *
  * <h3>Per-type static utilities</h3>
@@ -53,11 +57,10 @@
  *   <li>{@link Shorts}
  * </ul>
  *
- * <h3>Value types</h3>
+ * <h3>General static utilities</h3>
  *
  * <ul>
- *   <li>{@link UnsignedInteger}
- *   <li>{@link UnsignedLong}
+ *   <li>{@link Primitives}
  * </ul>
  */
 @ParametersAreNonnullByDefault
diff --git a/android/guava/src/com/google/common/util/concurrent/ListenableFuture.java b/android/guava/src/com/google/common/util/concurrent/ListenableFuture.java
@@ -36,10 +36,11 @@
  *
  * <p>The main purpose of {@code ListenableFuture} is to help you chain together a graph of
  * asynchronous operations. You can chain them together manually with calls to methods like {@link
- * Futures#transform(ListenableFuture, com.google.common.base.Function, Executor)
- * Futures.transform}, but you will often find it easier to use a framework. Frameworks automate the
- * process, often adding features like monitoring, debugging, and cancellation. Examples of
- * frameworks include:
+ * Futures#transform(ListenableFuture, com.google.common.base.Function, Executor) Futures.transform}
+ * (or {@link FluentFuture#transform(com.google.common.base.Function, Executor)
+ * FluentFuture.transform}), but you will often find it easier to use a framework. Frameworks
+ * automate the process, often adding features like monitoring, debugging, and cancellation.
+ * Examples of frameworks include:
  *
  * <ul>
  *   <li><a href="https://dagger.dev/producers.html">Dagger Producers</a>
diff --git a/android/guava/src/com/google/common/util/concurrent/package-info.java b/android/guava/src/com/google/common/util/concurrent/package-info.java
@@ -15,10 +15,11 @@
 /**
  * Concurrency utilities.
  *
- * <p>Commonly used types include {@link ListenableFuture} and {@link Service}.
+ * <p>Commonly used types include {@link ClosingFuture}, {@link ListenableFuture}, and {@link
+ * Service}.
  *
- * <p>Commonly used utilities include {@link Futures}, {@link MoreExecutors}, and {@link
- * ThreadFactoryBuilder}.
+ * <p>Commonly used utilities include {@link Futures}, {@link MoreExecutors}, {@link
+ * ThreadFactoryBuilder}, and {@link Uninterruptibles}.
  *
  * <p>This package is a part of the open-source <a href="https://github.com/google/guava">Guava</a>
  * library.
diff --git a/futures/listenablefuture1/src/com/google/common/util/concurrent/ListenableFuture.java b/futures/listenablefuture1/src/com/google/common/util/concurrent/ListenableFuture.java
@@ -36,10 +36,11 @@
  *
  * <p>The main purpose of {@code ListenableFuture} is to help you chain together a graph of
  * asynchronous operations. You can chain them together manually with calls to methods like {@link
- * Futures#transform(ListenableFuture, com.google.common.base.Function, Executor)
- * Futures.transform}, but you will often find it easier to use a framework. Frameworks automate the
- * process, often adding features like monitoring, debugging, and cancellation. Examples of
- * frameworks include:
+ * Futures#transform(ListenableFuture, com.google.common.base.Function, Executor) Futures.transform}
+ * (or {@link FluentFuture#transform(com.google.common.base.Function, Executor)
+ * FluentFuture.transform}), but you will often find it easier to use a framework. Frameworks
+ * automate the process, often adding features like monitoring, debugging, and cancellation.
+ * Examples of frameworks include:
  *
  * <ul>
  *   <li><a href="https://dagger.dev/producers.html">Dagger Producers</a>
diff --git a/guava/src/com/google/common/primitives/package-info.java b/guava/src/com/google/common/primitives/package-info.java
@@ -14,7 +14,7 @@
 
 /**
  * Static utilities for the eight primitive types and {@code void}, and value types for treating
- * them as unsigned.
+ * them as unsigned or storing them in immutable arrays.
  *
  * <p>This package is a part of the open-source <a href="https://github.com/google/guava">Guava</a>
  * library.
@@ -24,10 +24,14 @@
  *
  * <h2>Contents</h2>
  *
- * <h3>General static utilities</h3>
+ * <h3>Value types</h3>
  *
  * <ul>
- *   <li>{@link Primitives}
+ *   <li>{@link ImmutableDoubleArray}
+ *   <li>{@link ImmutableIntArray}
+ *   <li>{@link ImmutableLongrray}
+ *   <li>{@link UnsignedInteger}
+ *   <li>{@link UnsignedLong}
  * </ul>
  *
  * <h3>Per-type static utilities</h3>
@@ -53,11 +57,10 @@
  *   <li>{@link Shorts}
  * </ul>
  *
- * <h3>Value types</h3>
+ * <h3>General static utilities</h3>
  *
  * <ul>
- *   <li>{@link UnsignedInteger}
- *   <li>{@link UnsignedLong}
+ *   <li>{@link Primitives}
  * </ul>
  */
 @ParametersAreNonnullByDefault
diff --git a/guava/src/com/google/common/util/concurrent/ListenableFuture.java b/guava/src/com/google/common/util/concurrent/ListenableFuture.java
@@ -36,10 +36,11 @@
  *
  * <p>The main purpose of {@code ListenableFuture} is to help you chain together a graph of
  * asynchronous operations. You can chain them together manually with calls to methods like {@link
- * Futures#transform(ListenableFuture, com.google.common.base.Function, Executor)
- * Futures.transform}, but you will often find it easier to use a framework. Frameworks automate the
- * process, often adding features like monitoring, debugging, and cancellation. Examples of
- * frameworks include:
+ * Futures#transform(ListenableFuture, com.google.common.base.Function, Executor) Futures.transform}
+ * (or {@link FluentFuture#transform(com.google.common.base.Function, Executor)
+ * FluentFuture.transform}), but you will often find it easier to use a framework. Frameworks
+ * automate the process, often adding features like monitoring, debugging, and cancellation.
+ * Examples of frameworks include:
  *
  * <ul>
  *   <li><a href="https://dagger.dev/producers.html">Dagger Producers</a>
diff --git a/guava/src/com/google/common/util/concurrent/package-info.java b/guava/src/com/google/common/util/concurrent/package-info.java
@@ -15,10 +15,11 @@
 /**
  * Concurrency utilities.
  *
- * <p>Commonly used types include {@link ListenableFuture} and {@link Service}.
+ * <p>Commonly used types include {@link ClosingFuture}, {@link ListenableFuture}, and {@link
+ * Service}.
  *
- * <p>Commonly used utilities include {@link Futures}, {@link MoreExecutors}, and {@link
- * ThreadFactoryBuilder}.
+ * <p>Commonly used utilities include {@link Futures}, {@link MoreExecutors}, {@link
+ * ThreadFactoryBuilder}, and {@link Uninterruptibles}.
  *
  * <p>This package is a part of the open-source <a href="https://github.com/google/guava">Guava</a>
  * library.

Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,7 @@`
`14`	`14`
`15`	`15`	`/**`
`16`	`16`	`* Static utilities for the eight primitive types and {@code void}, and value types for treating`
`17`		`- * them as unsigned.`
	`17`	`+ * them as unsigned or storing them in immutable arrays.`
`18`	`18`	`*`
`19`	`19`	`* <p>This package is a part of the open-source <a href="https://github.com/google/guava">Guava</a>`
`20`	`20`	`* library.`
`@@ -24,10 +24,14 @@`
`24`	`24`	`*`
`25`	`25`	`* <h2>Contents</h2>`
`26`	`26`	`*`
`27`		`- * <h3>General static utilities</h3>`
	`27`	`+ * <h3>Value types</h3>`
`28`	`28`	`*`
`29`	`29`	`* <ul>`
`30`		`- * <li>{@link Primitives}`
	`30`	`+ * <li>{@link ImmutableDoubleArray}`
	`31`	`+ * <li>{@link ImmutableIntArray}`
	`32`	`+ * <li>{@link ImmutableLongrray}`
	`33`	`+ * <li>{@link UnsignedInteger}`
	`34`	`+ * <li>{@link UnsignedLong}`
`31`	`35`	`* </ul>`
`32`	`36`	`*`
`33`	`37`	`* <h3>Per-type static utilities</h3>`
`@@ -53,11 +57,10 @@`
`53`	`57`	`* <li>{@link Shorts}`
`54`	`58`	`* </ul>`
`55`	`59`	`*`
`56`		`- * <h3>Value types</h3>`
	`60`	`+ * <h3>General static utilities</h3>`
`57`	`61`	`*`
`58`	`62`	`* <ul>`
`59`		`- * <li>{@link UnsignedInteger}`
`60`		`- * <li>{@link UnsignedLong}`
	`63`	`+ * <li>{@link Primitives}`
`61`	`64`	`* </ul>`
`62`	`65`	`*/`
`63`	`66`	`@ParametersAreNonnullByDefault`
Original file line number	Diff line number	Diff line change
`@@ -15,10 +15,11 @@`
`15`	`15`	`/**`
`16`	`16`	`* Concurrency utilities.`
`17`	`17`	`*`
`18`		`- * <p>Commonly used types include {@link ListenableFuture} and {@link Service}.`
	`18`	`+ * <p>Commonly used types include {@link ClosingFuture}, {@link ListenableFuture}, and {@link`
	`19`	`+ * Service}.`
`19`	`20`	`*`
`20`		`- * <p>Commonly used utilities include {@link Futures}, {@link MoreExecutors}, and {@link`
`21`		`- * ThreadFactoryBuilder}.`
	`21`	`+ * <p>Commonly used utilities include {@link Futures}, {@link MoreExecutors}, {@link`
	`22`	`+ * ThreadFactoryBuilder}, and {@link Uninterruptibles}.`
`22`	`23`	`*`
`23`	`24`	`* <p>This package is a part of the open-source <a href="https://github.com/google/guava">Guava</a>`
`24`	`25`	`* library.`