From 372e9671eba3c1828cab9c3b01764f5544362bb4 Mon Sep 17 00:00:00 2001
From: Sergio Benitez <sb@sergio.bz>
Date: Sun, 26 Mar 2023 19:32:49 -0700
Subject: [PATCH] Clarify 'Responder' async I/O usage in docs.

Resolves #2286.
---
 core/lib/src/response/responder.rs | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/core/lib/src/response/responder.rs b/core/lib/src/response/responder.rs
index c3966d24..c6fbdd8b 100644
--- a/core/lib/src/response/responder.rs
+++ b/core/lib/src/response/responder.rs
@@ -106,8 +106,7 @@ use crate::request::Request;
 ///
 /// # Return Value
 ///
-/// A `Responder` returns a `Future` whose output type is a `Result<Response,
-/// Status>`.
+/// A `Responder` returns a `Result<Response, Status>`.
 ///
 ///   * An `Ok(Response)` indicates success. The `Response` will be written out
 ///     to the client.
@@ -145,6 +144,14 @@ use crate::request::Request;
 ///    _handler_ from its type signature also becomes more difficult. You should
 ///    avoid varying responses based on the `Request` value as much as possible.
 ///
+/// 4. Perform `async` I/O in Constructors
+///
+///    The `Responder` trait is not an `async` trait. This is not an oversight.
+///    Instead of performing `async` operations in what would be the
+///    `respond_to` method, perform them in a constructor for the responder. As
+///    an example, see [`NamedFile::open()`](crate::fs::NamedFile::open()),
+///    which performs the requisite I/O for `NamedFile`'s responder.
+///
 /// ## Lifetimes
 ///
 /// `Responder` has two lifetimes: `Responder<'r, 'o: 'r>`.