Advertise ClosingFuture from ListenableFuture, Futures, and FluentFuture.

Each of the three already has a passage about chaining operations and the alternatives for doing so; this adds a short pointer to `ClosingFuture` in each.

Fixes #4022
Fixes #8688

RELNOTES=n/a
PiperOrigin-RevId: 987494211

Author: ionik0

android/guava/src/com/google/common/util/concurrent/FluentFuture.java

@@ -65,6 +65,13 @@
  * need to adapt between {@code CompletableFuture} and {@code ListenableFuture}, consider <a
  * href="https://github.com/lukas-krecan/future-converter">Future Converter</a>.)
  *
+ * <h3>{@link ClosingFuture}</h3>
+ *
+ * <p>If the steps of your pipeline create objects that must be closed when the computation is done,
+ * such as database connections or file handles, use {@code ClosingFuture}. It supports the same
+ * kinds of derived steps as {@code FluentFuture} but closes those objects once the pipeline
+ * completes, fails, or is cancelled.
+ *
  * <h2>Extension</h2>
  *
  * If you want a class like {@code FluentFuture} but with extra methods, we recommend declaring your

android/guava/src/com/google/common/util/concurrent/Futures.java

@@ -72,7 +72,9 @@
  *   <li><a href="https://dagger.dev/producers.html">Dagger Producers</a>
  * </ul>
  *
- * <p>If you do chain your operations manually, you may want to use {@link FluentFuture}.
+ * <p>If you do chain your operations manually, you may want to use {@link FluentFuture}. If those
+ * operations create objects that must be closed when the computation is done, see {@link
+ * ClosingFuture}.
  *
  * @author Kevin Bourrillion
  * @author Nishant Thakkar

android/guava/src/com/google/common/util/concurrent/ListenableFuture.java

@@ -47,6 +47,10 @@
  *   <li><a href="https://dagger.dev/producers.html">Dagger Producers</a>
  * </ul>
  *
+ * <p>If the operations in your chain create objects that must be closed when the computation is
+ * done, such as database connections or file handles, consider {@link ClosingFuture}. It closes
+ * them once the whole computation completes, fails, or is cancelled.
+ *
  * <p>The main purpose of {@link #addListener addListener} is to support this chaining. You will
  * rarely use it directly, in part because it does not provide direct access to the {@code Future}
  * result. (If you want such access, you may prefer {@link Futures#addCallback

futures/listenablefuture1/src/com/google/common/util/concurrent/ListenableFuture.java

@@ -47,6 +47,10 @@
  *   <li><a href="https://dagger.dev/producers.html">Dagger Producers</a>
  * </ul>
  *
+ * <p>If the operations in your chain create objects that must be closed when the computation is
+ * done, such as database connections or file handles, consider {@link ClosingFuture}. It closes
+ * them once the whole computation completes, fails, or is cancelled.
+ *
  * <p>The main purpose of {@link #addListener addListener} is to support this chaining. You will
  * rarely use it directly, in part because it does not provide direct access to the {@code Future}
  * result. (If you want such access, you may prefer {@link Futures#addCallback

guava/src/com/google/common/util/concurrent/FluentFuture.java

@@ -65,6 +65,13 @@
  * need to adapt between {@code CompletableFuture} and {@code ListenableFuture}, consider <a
  * href="https://github.com/lukas-krecan/future-converter">Future Converter</a>.)
  *
+ * <h3>{@link ClosingFuture}</h3>
+ *
+ * <p>If the steps of your pipeline create objects that must be closed when the computation is done,
+ * such as database connections or file handles, use {@code ClosingFuture}. It supports the same
+ * kinds of derived steps as {@code FluentFuture} but closes those objects once the pipeline
+ * completes, fails, or is cancelled.
+ *
  * <h2>Extension</h2>
  *
  * If you want a class like {@code FluentFuture} but with extra methods, we recommend declaring your

guava/src/com/google/common/util/concurrent/Futures.java

@@ -72,7 +72,9 @@
  *   <li><a href="https://dagger.dev/producers.html">Dagger Producers</a>
  * </ul>
  *
- * <p>If you do chain your operations manually, you may want to use {@link FluentFuture}.
+ * <p>If you do chain your operations manually, you may want to use {@link FluentFuture}. If those
+ * operations create objects that must be closed when the computation is done, see {@link
+ * ClosingFuture}.
  *
  * @author Kevin Bourrillion
  * @author Nishant Thakkar

guava/src/com/google/common/util/concurrent/ListenableFuture.java

@@ -47,6 +47,10 @@
  *   <li><a href="https://dagger.dev/producers.html">Dagger Producers</a>
  * </ul>
  *
+ * <p>If the operations in your chain create objects that must be closed when the computation is
+ * done, such as database connections or file handles, consider {@link ClosingFuture}. It closes
+ * them once the whole computation completes, fails, or is cancelled.
+ *
  * <p>The main purpose of {@link #addListener addListener} is to support this chaining. You will
  * rarely use it directly, in part because it does not provide direct access to the {@code Future}
  * result. (If you want such access, you may prefer {@link Futures#addCallback