From f3fb74df310d070d91df7995c942f223cba6720a Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Thu, 3 Oct 2024 21:12:50 -0400
Subject: [PATCH] Document how `BoxFuture`s / `BoxStream`s are often made
 (#2887)

---
 futures-core/src/future.rs | 10 ++++++++++
 futures-core/src/stream.rs | 10 ++++++++++
 2 files changed, 20 insertions(+)

diff --git a/futures-core/src/future.rs b/futures-core/src/future.rs
index 7540cd027e..30c0323a6b 100644
--- a/futures-core/src/future.rs
+++ b/futures-core/src/future.rs
@@ -9,10 +9,20 @@ pub use core::future::Future;
 
 /// An owned dynamically typed [`Future`] for use in cases where you can't
 /// statically type your result or need to add some indirection.
+///
+/// This type is often created by the [`boxed`] method on [`FutureExt`]. See its documentation for more.
+///
+/// [`boxed`]: https://docs.rs/futures/latest/futures/future/trait.FutureExt.html#method.boxed
+/// [`FutureExt`]: https://docs.rs/futures/latest/futures/future/trait.FutureExt.html
 #[cfg(feature = "alloc")]
 pub type BoxFuture<'a, T> = Pin<alloc::boxed::Box<dyn Future<Output = T> + Send + 'a>>;
 
 /// `BoxFuture`, but without the `Send` requirement.
+///
+/// This type is often created by the [`boxed_local`] method on [`FutureExt`]. See its documentation for more.
+///
+/// [`boxed_local`]: https://docs.rs/futures/latest/futures/future/trait.FutureExt.html#method.boxed_local
+/// [`FutureExt`]: https://docs.rs/futures/latest/futures/future/trait.FutureExt.html
 #[cfg(feature = "alloc")]
 pub type LocalBoxFuture<'a, T> = Pin<alloc::boxed::Box<dyn Future<Output = T> + 'a>>;
 
diff --git a/futures-core/src/stream.rs b/futures-core/src/stream.rs
index 19114e7dab..dd07d5aa01 100644
--- a/futures-core/src/stream.rs
+++ b/futures-core/src/stream.rs
@@ -6,10 +6,20 @@ use core::task::{Context, Poll};
 
 /// An owned dynamically typed [`Stream`] for use in cases where you can't
 /// statically type your result or need to add some indirection.
+///
+/// This type is often created by the [`boxed`] method on [`StreamExt`]. See its documentation for more.
+///
+/// [`boxed`]: https://docs.rs/futures/latest/futures/stream/trait.StreamExt.html#method.boxed
+/// [`StreamExt`]: https://docs.rs/futures/latest/futures/stream/trait.StreamExt.html
 #[cfg(feature = "alloc")]
 pub type BoxStream<'a, T> = Pin<alloc::boxed::Box<dyn Stream<Item = T> + Send + 'a>>;
 
 /// `BoxStream`, but without the `Send` requirement.
+///
+/// This type is often created by the [`boxed_local`] method on [`StreamExt`]. See its documentation for more.
+///
+/// [`boxed_local`]: https://docs.rs/futures/latest/futures/stream/trait.StreamExt.html#method.boxed_local
+/// [`StreamExt`]: https://docs.rs/futures/latest/futures/stream/trait.StreamExt.html
 #[cfg(feature = "alloc")]
 pub type LocalBoxStream<'a, T> = Pin<alloc::boxed::Box<dyn Stream<Item = T> + 'a>>;