docs(service): add HttpService documentation (#3869)

this commit introduces some additional documentation to the
`HttpService` trait, and the `Service` trait.

notably, this commit introduces some intradoc links, so that rustdoc
will render links to types like `http::Request` and `http::Response`, or
to the `Body` trait.

additionally, mention of `hyper-util` is added to the `Service` trait,
to direct users to the glue implementations that they will likely need
to interact with e.g. `tower`.

Signed-off-by: katelyn martin <[email protected]>

Author: cratelyn

src/service/http.rs

@@ -5,19 +5,32 @@ use crate::body::Body;
 use crate::service::service::Service;
 use crate::{Request, Response};
 
-/// An asynchronous function from `Request` to `Response`.
+/// An asynchronous function from [`Request`] to [`Response`].
+///
+/// This is a *sealed* trait, meaning that it can not be implemented directly. Rather, it is an
+/// alias for [`Service`]s that accept a [`Request`] and return a [`Future`] that resolves to a
+/// [`Response`]. External callers should implement [`Service`] instead.
+///
+/// Rather than being generic over the request and response, this trait is generic across the
+/// request [`Body`] and response [`Body`].
+///
+/// See the crate-level [`service`][crate::service] documentation for more information.
+///
+/// See [`Service`] for more information.
 pub trait HttpService<ReqBody>: sealed::Sealed<ReqBody> {
-    /// The `Body` body of the `http::Response`.
+    /// The [`Body`] body of the [`Response`].
     type ResBody: Body;
 
-    /// The error type that can occur within this `Service`.
+    /// The error type that can occur within this [`Service`].
     ///
-    /// Note: Returning an `Error` to a hyper server will cause the connection
-    /// to be abruptly aborted. In most cases, it is better to return a `Response`
-    /// with a 4xx or 5xx status code.
+    /// Note: Returning an `Error` to a hyper server, the behavior depends on the protocol. In
+    /// most cases, hyper will cause the connection to be abruptly aborted. In most cases, it is
+    /// better to return a `Response` with a 4xx or 5xx status code.
+    ///
+    /// See [`Service::Error`] for more information.
     type Error: Into<Box<dyn StdError + Send + Sync>>;
 
-    /// The `Future` returned by this `Service`.
+    /// The [`Future`] returned by this [`Service`].
     type Future: Future<Output = Result<Response<Self::ResBody>, Self::Error>>;
 
     #[doc(hidden)]

src/service/service.rs

@@ -9,14 +9,26 @@ use std::future::Future;
 /// # Functional
 ///
 /// A `Service` is a function of a `Request`. It immediately returns a
-/// `Future` representing the eventual completion of processing the
+/// [`Future`] representing the eventual completion of processing the
 /// request. The actual request processing may happen at any time in the
 /// future, on any thread or executor. The processing may depend on calling
 /// other services. At some point in the future, the processing will complete,
-/// and the `Future` will resolve to a response or error.
+/// and the [`Future`] will resolve to a response or an error.
 ///
 /// At a high level, the `Service::call` function represents an RPC request. The
 /// `Service` value can be a server or a client.
+///
+/// # Utilities
+///
+/// The [`hyper-util`][util] crate provides facilities to bridge this trait to
+/// other libraries, such as [`tower`][tower], which might provide their
+/// own `Service` variants.
+///
+/// See [`hyper_util::service`][util-service] for more information.
+///
+/// [tower]: https://docs.rs/tower
+/// [util]: https://docs.rs/hyper-util
+/// [util-service]: https://docs.rs/hyper-util/latest/hyper_util/service/index.html
 pub trait Service<Request> {
     /// Responses given by the service.
     type Response;
@@ -37,7 +49,7 @@ pub trait Service<Request> {
     /// - It prepares the way for async fn,
     ///   since then the future only borrows `&self`, and thus a Service can concurrently handle
     ///   multiple outstanding requests at once.
-    /// - It's clearer that Services can likely be cloned
+    /// - It's clearer that Services can likely be cloned.
     /// - To share state across clones, you generally need `Arc<Mutex<_>>`
     ///   That means you're not really using the `&mut self` and could do with a `&self`.
     ///   The discussion on this is here: <https://github.com/hyperium/hyper/issues/3040>