docs: improve api descriptions/examples

Author: joseluisq

src/lib.rs

@@ -3,17 +3,18 @@
 //! # hyper_middleware
 //!
 //! `hyper_middleware` is a complement set of HTTP middlewares with a small Hyper Service to get started with a HTTP server easily.
-//! This module only supports Hyper `0.14.x`.
+//! This module only supports Hyper `0.14`.
 //!
 //! ## Features
 //!
-//! - Compact Middleware and Handler System inspired by [The Iron Framework](https://github.com/iron/iron).
-//! - Simple [Hyper Service](https://docs.rs/hyper/latest/hyper/service/trait.Service.html) with convenient __Remote Address__ access.
-//! - Convenient `Error` and `Result` types powered by [anyhow](https://github.com/dtolnay/anyhow).
+//! - Compact [Middleware & Handler System][`middleware`] inspired by [The Iron Framework](https://github.com/iron/iron).
+//! - Simple [Hyper Service][`hyper::service::Service`] with [Remote Address][`hyper::server::conn::AddrStream`] access.
+//! - Convenient [`Error`] and [`Result`] types powered by [anyhow](https://github.com/dtolnay/anyhow).
+//!
 
-mod middleware;
-mod service;
-mod types;
+pub mod middleware;
+pub mod service;
+pub mod types;
 
 pub use middleware::*;
 pub use service::*;

src/middleware.rs

@@ -1,13 +1,10 @@
-//! The Iron middleware and handler system for latest Hyper `0.14.x`.
-//! It is borrowed from the Iron project and adapted at convenience.
+//! The middleware and handler system module.
 //!
-//! <https://github.com/iron/iron/blob/master/iron/src/middleware/mod.rs>
+//! It's highly inspired by [The Iron middleware & handler system](https://github.com/iron/iron/blob/master/iron/src/middleware/mod.rs) and intended to work with latest [Hyper][`hyper`] `0.14`.
 //!
-//! The Iron middleware and handler system are the fundamental building blocks
+//! The middleware and handler system are the fundamental building blocks
 //! for handling HTTP requests and generating responses with Hyper.
 //!
-//! This module is intended to work with latest Hyper `0.14.x`.
-//!
 //! # Handlers
 //!
 //! A `Handler` will produce a `Response` given a `Request`. Most handlers are
@@ -19,7 +16,7 @@
 //! Here's an example of a `Handler`:
 //!
 //! ```rust
-//! use hyper_middleware::{Request, Response};
+//! use hyper_middleware::{Request, Response, Result};
 //!
 //! fn hello_handler(req: &mut Request) -> Result<Response> {
 //!     Ok(Response::builder().body(Body::from("¡Hola!")).unwrap())
@@ -56,32 +53,41 @@
 //!
 //! ```rust
 //! use hyper::Server;
-//! use hyper_middleware::{Request, Response, RouterService};
-//!
-//! fn hello_handler(req: &mut Request) -> Result<Response> {
-//!     Ok(Response::builder().body(Body::from("¡Hola!")).unwrap())
-//! };
+//! use hyper_middleware::{BeforeMiddleware, Body, Chain, Request, Response, Result, Service};
+//!
+//! fn hello_handler(_req: &mut Request) -> Result<Response> {
+//!      let mut resp = Response::new(Body::from("¡Hola!"));
+//!      resp.headers_mut().insert(
+//!          header::CONTENT_TYPE,
+//!          "text/html; charset=utf-8".parse().unwrap(),
+//!      );
+//!      Ok(resp)
+//! }
 //!
-//! struct RequestLoggingMiddleware {};
+//! struct RequestLoggingMiddleware {}
 //! impl BeforeMiddleware for RequestLoggingMiddleware {
-//!     fn before(&self, req: &mut Request) -> Result<()> {
+//!     fn before(&self, req: &mut Request) -> Result {
 //!         println!("{:?}", req);
 //!         Ok(())
 //!     }
 //! }
 //!
+//! #[tokio::main(flavor = "multi_thread")]
 //! async fn main() -> Result {
 //!     let mut chain = Chain::new(hello_handler);
+//!     // Plug in the custom middleware(s)
 //!     chain.link_before(RequestLoggingMiddleware {});
 //!
 //!     let addr = ([127, 0, 0, 1], 8787).into();
-//!     let service = RouterService::new(chain);
-
+//!     let service = Service::new(chain);
 //!     let server = Server::bind(&addr).serve(service);
 //!     println!("Listening on http://{}", addr);
 //!
 //!     server.await?;
+//!
+//!     Ok(())
 //! }
+
 //! ```
 //!
 //! # The Request Handling Flow

src/service.rs

@@ -1,3 +1,42 @@
+//! The Hyper service module.
+//!
+//! It provides a [Hyper Service][`hyper::service::Service`] implementation intended to work with
+//! the [Hyper Server Builder][`hyper::server::Builder`].
+//!
+//! The service allows to bind a [`Chain`][`super::Chain`] of middlewares.
+//!
+//! ## Example
+//!
+//! ```rust
+//! use hyper::Server;
+//! use hyper_middleware::{
+//!     Body, Handler, Request, Response, Result, Service
+//! };
+//!
+//! struct Application {}
+//! impl Handler for Application {
+//!     fn handle(&self, _req: &mut Request) -> Result<Response> {
+//!         // Create a response and send it back to the middlewares chain
+//!         Ok(Response::new(Body::from("¡Hola!")))
+//!     }
+//! }
+//!
+//! #[tokio::main(flavor = "multi_thread")]
+//! async fn main() -> Result {
+//!     let mut my_handler = Chain::new(Application {});
+//!
+//!     let my_service = Service::new(my_handler);
+//!
+//!     let addr = ([127, 0, 0, 1], 8787).into();
+//!     let server = Server::bind(&addr).serve(my_service);
+//!
+//!     println!("Listening on http://{}", addr);
+//!
+//!     server.await?;
+//!     Ok(())
+//! }
+//! ```
+
 use hyper::server::conn::AddrStream;
 use hyper::service::Service as HyperService;
 use std::convert::Infallible;
@@ -7,7 +46,7 @@ use std::task::{Context, Poll};
 use self::handler_service::{HandlerService, HandlerServiceBuilder};
 use crate::middleware::Handler;
 
-/// Hyper Service entry point which hosts a `Handler`.
+/// A [Hyper Service][`hyper::service::Service`] entry point which hosts a [`Handler`].
 pub struct Service<H> {
     builder: HandlerServiceBuilder<H>,
 }

src/types.rs

@@ -1,14 +1,16 @@
-/// A `hyper::Body` type alias.
+//! Set of types aliases for convenience.
+
+/// A [`hyper::Body`] type alias.
 pub type Body = hyper::Body;
 
-/// A `hyper::Request<Body>` type alias.
+/// A [`hyper::Request<Body>`] type alias.
 pub type Request<T = Body> = hyper::Request<T>;
 
-/// A `hyper::Response<Body>` type alias.
+/// A [`hyper::Response<Body>`] type alias.
 pub type Response<T = Body> = hyper::Response<T>;
 
-/// An `anyhow::Error` type alias.
+/// An [`anyhow::Error`] type alias.
 pub type Error = anyhow::Error;
 
-/// An `anyhow::Result` type alias.
+/// An [`anyhow::Result`] type alias.
 pub type Result<T = (), E = Error> = anyhow::Result<T, E>;