docs(server): polish server connection docs

src/server/conn/http1.rs

@@ -22,9 +22,12 @@ type Http1Dispatcher<T, B, S> = proto::h1::Dispatcher<
 >;
 
 pin_project_lite::pin_project! {
-    /// A future binding an http1 connection with a Service.
+    /// A [`Future`](core::future::Future) representing an HTTP/1 connection, bound to a
+    /// [`Service`](crate::service::Service), returned from
+    /// [`Builder::serve_connection`](struct.Builder.html#method.serve_connection).
     ///
-    /// Polling this future will drive HTTP forward.
+    /// To drive HTTP on this connection this future **must be polled**, typically with
+    /// `.await`. If it isn't polled, no progress will be made on this connection.
     #[must_use = "futures do nothing unless polled"]
     pub struct Connection<T, S>
     where

src/server/conn/http2.rs

@@ -16,9 +16,12 @@ use crate::service::HttpService;
 use crate::{common::time::Time, rt::Timer};
 
 pin_project! {
-    /// A future binding an HTTP/2 connection with a Service.
+    /// A [`Future`](core::future::Future) representing an HTTP/2 connection, bound to a
+    /// [`Service`](crate::service::Service), returned from
+    /// [`Builder::serve_connection`](struct.Builder.html#method.serve_connection).
     ///
-    /// Polling this future will drive HTTP forward.
+    /// To drive HTTP on this connection this future **must be polled**, typically with
+    /// `.await`. If it isn't polled, no progress will be made on this connection.
     #[must_use = "futures do nothing unless polled"]
     pub struct Connection<T, S, E>
     where

src/server/conn/mod.rs

@@ -5,8 +5,14 @@
 //! are not handled at this level. This module provides the building blocks to
 //! customize those things externally.
 //!
-//! This module is split by HTTP version. Both work similarly, but do have
-//! specific options on each builder.
+//! This module is split by HTTP version, providing a connection builder for
+//! each. They work similarly, but they each have specific options.
+//!
+//! If your server needs to support both versions, an auto-connection builder is
+//! provided in the [`hyper-util`](https://github.com/hyperium/hyper-util/tree/master)
+//! crate. This builder wraps the HTTP/1 and HTTP/2 connection builders from this
+//! module, allowing you to set configuration for both. The builder will then check
+//! the version of the incoming connection and serve it accordingly.
 
 #[cfg(feature = "http1")]
 pub mod http1;

src/service/service.rs

@@ -35,6 +35,6 @@ pub trait Service<Request> {
     /// - 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
-    /// To see the discussion on this see: https://github.com/hyperium/hyper/issues/3040
+    /// To see the discussion on this see: <https://github.com/hyperium/hyper/issues/3040>
     fn call(&self, req: Request) -> Self::Future;
 }