Update ntex_service documentation (#148)

ntex-service/src/apply.rs

@@ -2,7 +2,7 @@ use std::{future::Future, marker::PhantomData, pin::Pin, task::Context, task::Po
 
 use super::{IntoService, IntoServiceFactory, Service, ServiceFactory};
 
-/// Apply tranform function to a service.
+/// Apply transform function to a service.
 pub fn apply_fn<T, Req, F, R, In, Out, Err, U>(
     service: U,
     f: F,
@@ -16,7 +16,7 @@ where
     Apply::new(service.into_service(), f)
 }
 
-/// Service factory that prodices `apply_fn` service.
+/// Service factory that produces `apply_fn` service.
 pub fn apply_fn_factory<T, Req, Cfg, F, R, In, Out, Err, U>(
     service: U,
     f: F,

ntex-service/src/lib.rs

@@ -1,3 +1,5 @@
+//! See [`Service`] docs for information on this crate's foundational trait.
+
 #![deny(rust_2018_idioms, warnings)]
 #![allow(clippy::type_complexity)]
 
@@ -23,48 +25,66 @@ pub use self::map_config::{map_config, map_config_service, unit_config};
 pub use self::pipeline::{pipeline, pipeline_factory, Pipeline, PipelineFactory};
 pub use self::transform::{apply, Identity, Transform};
 
-/// An asynchronous function from `Request` to a `Response`.
+/// An asynchronous function of `Request` to a `Response`.
 ///
-/// `Service` represents a service that represanting interation, taking requests and giving back
+/// The `Service` trait represents a request/response interaction, receiving requests and returning
-/// replies. You can think about service as a function with one argument and result as a return
+/// replies. You can think about service as a function with one argument that returns some result
-/// type. In general form it looks like `async fn(Req) -> Result<Res, Err>`. `Service`
+/// asynchronously. Conceptually, the operation looks like this:
-/// trait just generalizing form of this function. Each parameter described as an assotiated type.
-///
-/// Services provides a symmetric and uniform API, same abstractions represents
-/// clients and servers. Services describe only `transforamtion` operation
-/// which encorouge to simplify api surface and phrases `value transformation`.
-/// That leads to simplier design of each service. That also allows better testability
-/// and better composition.
-///
-/// Services could be represented in several different forms. In general,
-/// Service is a type that implements `Service` trait.
 ///
 /// ```rust,ignore
+/// async fn(Request) -> Result<Response, Error>
+/// ```
+///
+/// The `Service` trait just generalizes this form. Requests are defined as a generic type parameter
+/// and responses and other details are defined as associated types on the trait impl. Notice that
+/// this design means that services can receive many request types and converge them to a single
+/// response type.
+///
+/// Services can also have mutable state that influence computation by using a `Cell`, `RefCell`
+/// or `Mutex`. Services intentionally do not take `&mut self` to reduce overhead in the
+/// common cases.
+///
+/// `Service` provides a symmetric and uniform API; the same abstractions can be used to represent
+/// both clients and servers. Services describe only _transformation_ operations which encourage
+/// simple API surfaces. This leads to simpler design of each service, improves test-ability and
+/// makes composition easier.
+///
+/// ```rust
+/// # use std::convert::Infallible;
+/// # use std::future::Future;
+/// # use std::pin::Pin;
+/// # use std::task::{Context, Poll};
+/// #
+/// # use ntex_service::Service;
+///
 /// struct MyService;
 ///
-/// impl Service for MyService {
+/// impl Service<u8> for MyService {
-///      type Request = u8;
+///     type Response = u64;
-///      type Response = u64;
+///     type Error = Infallible;
-///      type Error = MyError;
+///     type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
-///      type Future = Pin<Box<Future<Output=Result<Self::Response, Self::Error>>>;
 ///
-///      fn poll_ready(&self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { ... }
+///     fn poll_ready(&self, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
+///         Poll::Ready(Ok(()))
+///     }
 ///
-///      fn call(&self, req: Self::Request) -> Self::Future { ... }
+///     fn call(&self, req: u8) -> Self::Future {
+///         Box::pin(std::future::ready(Ok(req as u64)))
+///     }
 /// }
 /// ```
 ///
-/// Service can have mutable state that influence computation.
+/// Sometimes it is not necessary to implement the Service trait. For example, the above service
-/// This service could be rewritten as a simple function:
+/// could be rewritten as a simple function and passed to [`fn_service`](fn_service()).
 ///
 /// ```rust,ignore
-/// async fn my_service(req: u8) -> Result<u64, MyError>;
+/// async fn my_service(req: u8) -> Result<u64, Infallible>;
 /// ```
 pub trait Service<Req> {
     /// Responses given by the service.
     type Response;
 
-    /// Errors produced by the service.
+    /// Errors produced by the service when polling readiness or executing call.
     type Error;
 
     /// The future response value.
@@ -72,26 +92,24 @@ pub trait Service<Req> {
 
     /// Returns `Ready` when the service is able to process requests.
     ///
-    /// If the service is at capacity, then `Pending` is returned and the task
+    /// If the service is at capacity, then `Pending` is returned and the task is notified when
-    /// is notified when the service becomes ready again. This function is
+    /// the service becomes ready again. This function is expected to be called while on a task.
-    /// expected to be called while on a task.
     ///
-    /// This is a **best effort** implementation. False positives are permitted.
+    /// This is a **best effort** implementation. False positives are permitted. It is permitted for
-    /// It is permitted for the service to return `Ready` from a `poll_ready`
+    /// the service to return `Ready` from a `poll_ready` call and the next invocation of `call`
-    /// call and the next invocation of `call` results in an error.
+    /// results in an error.
     ///
-    /// There are several notes to consider:
+    /// # Notes
     ///
     /// 1. `.poll_ready()` might be called on different task from actual service call.
-    ///
+    /// 1. In case of chained services, `.poll_ready()` is called for all services at once.
-    /// 2. In case of chained services, `.poll_ready()` get called for all services at once.
     fn poll_ready(&self, ctx: &mut task::Context<'_>) -> Poll<Result<(), Self::Error>>;
 
     #[inline]
     #[allow(unused_variables)]
     /// Shutdown service.
     ///
-    /// Returns `Ready` when the service is properly shutdowned. This method might be called
+    /// Returns `Ready` when the service is properly shutdowns. This method might be called
     /// after it returns `Ready`.
     fn poll_shutdown(&self, ctx: &mut task::Context<'_>, is_error: bool) -> Poll<()> {
         Poll::Ready(())
@@ -99,25 +117,22 @@ pub trait Service<Req> {
 
     /// Process the request and return the response asynchronously.
     ///
-    /// This function is expected to be callable off task. As such,
+    /// This function is expected to be callable off-task. As such, implementations of `call`
-    /// implementations should take care to not call `poll_ready`. If the
+    /// should take care to not call `poll_ready`. If the  service is at capacity and the request
-    /// service is at capacity and the request is unable to be handled, the
+    /// is unable to be handled, the returned `Future` should resolve to an error.
-    /// returned `Future` should resolve to an error.
     ///
-    /// Calling `call` without calling `poll_ready` is permitted. The
+    /// Invoking `call` without first invoking `poll_ready` is permitted. Implementations must be
-    /// implementation must be resilient to this fact.
+    /// resilient to this fact.
     fn call(&self, req: Req) -> Self::Future;
 
     #[inline]
-    /// Map this service's output to a different type, returning a new service
+    /// Map this service's output to a different type, returning a new service of the resulting type.
-    /// of the resulting type.
     ///
-    /// This function is similar to the `Option::map` or `Iterator::map` where
+    /// This function is similar to the `Option::map` or `Iterator::map` where it will change
-    /// it will change the type of the underlying service.
+    /// the type of the underlying service.
     ///
-    /// Note that this function consumes the receiving service and returns a
+    /// Note that this function consumes the receiving service and returns a wrapped version of it,
-    /// wrapped version of it, similar to the existing `map` methods in the
+    /// similar to the existing `map` methods in the standard library.
-    /// standard library.
     fn map<F, Res>(self, f: F) -> crate::dev::Map<Self, F, Req, Res>
     where
         Self: Sized,
@@ -129,12 +144,11 @@ pub trait Service<Req> {
     #[inline]
     /// Map this service's error to a different error, returning a new service.
     ///
-    /// This function is similar to the `Result::map_err` where it will change
+    /// This function is similar to the `Result::map_err` where it will change the error type of
-    /// the error type of the underlying service. This is useful for example to
+    /// the underlying service. This is useful for example to ensure that services have the same
-    /// ensure that services have the same error type.
+    /// error type.
     ///
-    /// Note that this function consumes the receiving service and returns a
+    /// Note that this function consumes the receiving service and returns a wrapped version of it.
-    /// wrapped version of it.
     fn map_err<F, E>(self, f: F) -> crate::dev::MapErr<Self, Req, F, E>
     where
         Self: Sized,
@@ -144,26 +158,28 @@ pub trait Service<Req> {
     }
 }
 
-/// Creates new `Service` values.
+/// Factory for creating `Service`s.
 ///
-/// Acts as a service factory. This is useful for cases where new `Service`
+/// This is useful for cases where new `Service`s must be produced. One case is a TCP server
-/// values must be produced. One case is a TCP server listener. The listener
+/// listener: a listener accepts new connections, constructs a new `Service` for each using
-/// accepts new TCP streams, obtains a new `Service` value using the
+/// the `ServiceFactory` trait, and uses the new `Service` to process inbound requests on that
-/// `ServiceFactory` trait, and uses that new `Service` value to process inbound
+/// new connection.
-/// requests on that new TCP stream.
 ///
 /// `Config` is a service factory configuration type.
+///
+/// Simple factories may be able to use [`fn_factory`] or [`fn_factory_with_config`] to
+/// reduce boilerplate.
 pub trait ServiceFactory<Req, Cfg = ()> {
-    /// Responses given by the service
+    /// Responses given by the created services.
     type Response;
 
-    /// Errors produced by the service
+    /// Errors produced by the created services.
     type Error;
 
-    /// The `Service` value created by this factory
+    /// The kind of `Service` created by this factory.
     type Service: Service<Req, Response = Self::Response, Error = Self::Error>;
 
-    /// Errors produced while building a service.
+    /// Errors potentially raised while building a service.
     type InitError;
 
     /// The future of the `ServiceFactory` instance.

ntex-service/src/pipeline.rs

@@ -8,7 +8,7 @@ use crate::then::{Then, ThenFactory};
 use crate::transform::{ApplyTransform, Transform};
 use crate::{IntoService, IntoServiceFactory, Service, ServiceFactory};
 
-/// Contruct new pipeline with one service in pipeline chain.
+/// Constructs new pipeline with one service in pipeline chain.
 pub fn pipeline<T, R, F>(service: F) -> Pipeline<T, R>
 where
     T: Service<R>,
@@ -20,7 +20,7 @@ where
     }
 }
 
-/// Contruct new pipeline factory with one service factory.
+/// Constructs new pipeline factory with one service factory.
 pub fn pipeline_factory<T, R, C, F>(factory: F) -> PipelineFactory<T, R, C>
 where
     T: ServiceFactory<R, C>,