From 9aab9116006b694fc0ac93df26ca2b0dfe6262bc Mon Sep 17 00:00:00 2001
From: Matt Fellenz <matt@felle.nz>
Date: Sat, 23 Apr 2022 13:57:11 -0700
Subject: [PATCH] Improve documentation for FromRequest::Future (#2734)

Co-authored-by: Rob Ede <robjtede@icloud.com>
---
 actix-web/src/extract.rs | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/actix-web/src/extract.rs b/actix-web/src/extract.rs
index 7d187c90a28..d4f5cc91fab 100644
--- a/actix-web/src/extract.rs
+++ b/actix-web/src/extract.rs
@@ -66,13 +66,29 @@ pub trait FromRequest: Sized {
     /// The associated error which can be returned.
     type Error: Into<Error>;
 
-    /// Future that resolves to a Self.
+    /// Future that resolves to a `Self`.
+    ///
+    /// To use an async function or block, the futures must be boxed. The following snippet will be
+    /// common when creating async/await extractors (that do not consume the body).
+    ///
+    /// ```ignore
+    /// type Future = Pin<Box<dyn Future<Output = Result<Self, Self::Error>>>>;
+    /// // or
+    /// type Future = futures_util::future::LocalBoxFuture<'static, Result<Self, Self::Error>>;
+    ///
+    /// fn from_request(req: HttpRequest, ...) -> Self::Future {
+    ///     let req = req.clone();
+    ///     Box::pin(async move {
+    ///         ...
+    ///     })
+    /// }
+    /// ```
     type Future: Future<Output = Result<Self, Self::Error>>;
 
-    /// Create a Self from request parts asynchronously.
+    /// Create a `Self` from request parts asynchronously.
     fn from_request(req: &HttpRequest, payload: &mut Payload) -> Self::Future;
 
-    /// Create a Self from request head asynchronously.
+    /// Create a `Self` from request head asynchronously.
     ///
     /// This method is short for `T::from_request(req, &mut Payload::None)`.
     fn extract(req: &HttpRequest) -> Self::Future {