docs(service): document service utilities (#180)

this commit introduces some additional documentation to the `service`
submodule, and the glue types like `TowerToHyperService` and
`TowerToHyperServiceFuture`.

links to relevant related documentation like `hyper::service`, and the
documentation of `tower::Service`.

this is closely related to hyperium/hyper#3869, which proposes a similar
documentation pass over `hyper`'s own `service` facilities.

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

Author: cratelyn

src/service/glue.rs

@@ -7,14 +7,22 @@ use std::{
 
 use super::Oneshot;
 
-/// A tower service converted into a hyper service.
+/// A tower [`Service`][tower-svc] converted into a hyper [`Service`][hyper-svc].
+///
+/// This wraps an inner tower service `S` in a [`hyper::service::Service`] implementation. See
+/// the module-level documentation of [`service`][crate::service] for more information about using
+/// [`tower`][tower] services and middleware with [`hyper`].
+///
+/// [hyper-svc]: hyper::service::Service
+/// [tower]: https://docs.rs/tower/latest/tower/
+/// [tower-svc]: https://docs.rs/tower/latest/tower/trait.Service.html
 #[derive(Debug, Copy, Clone)]
 pub struct TowerToHyperService<S> {
     service: S,
 }
 
 impl<S> TowerToHyperService<S> {
-    /// Create a new `TowerToHyperService` from a tower service.
+    /// Create a new [`TowerToHyperService`] from a tower service.
     pub fn new(tower_service: S) -> Self {
         Self {
             service: tower_service,
@@ -39,6 +47,9 @@ where
 
 pin_project! {
     /// Response future for [`TowerToHyperService`].
+    ///
+    /// This future is acquired by [`call`][hyper::service::Service::call]ing a
+    /// [`TowerToHyperService`].
     pub struct TowerToHyperServiceFuture<S, R>
     where
         S: tower_service::Service<R>,

src/service/mod.rs

@@ -1,4 +1,25 @@
 //! Service utilities.
+//!
+//! [`hyper::service`] provides a [`Service`][hyper-svc] trait, representing an asynchronous
+//! function from a `Request` to a `Response`. This provides an interface allowing middleware for
+//! network application to be written in a modular and reusable way.
+//!
+//! This submodule provides an assortment of utilities for working with [`Service`][hyper-svc]s.
+//! See the module-level documentation of [`hyper::service`] for more information.
+//!
+//! # Tower
+//!
+//! While [`hyper`] uses its own notion of a [`Service`][hyper-svc] internally, many other
+//! libraries use a library such as [`tower`][tower] to provide the fundamental model of an
+//! asynchronous function.
+//!
+//! The [`TowerToHyperService`] type provided by this submodule can be used to bridge these
+//! ecosystems together. By wrapping a [`tower::Service`][tower-svc] in [`TowerToHyperService`],
+//! it can be passed into [`hyper`] interfaces that expect a [`hyper::service::Service`].
+//!
+//! [hyper-svc]: hyper::service::Service
+//! [tower]: https://docs.rs/tower/latest/tower/
+//! [tower-svc]: https://docs.rs/tower/latest/tower/trait.Service.html
 
 #[cfg(feature = "service")]
 mod glue;