improve tower-layer docs (#834)

* improve tower-layer docs

* fix compile issues

Author: ripytide

tower-layer/src/identity.rs

@@ -7,21 +7,35 @@ use core::fmt;
 /// service without modifying it.
 ///
 /// [`Service`]: https://docs.rs/tower-service/latest/tower_service/trait.Service.html
+///
+/// # Examples
+///
+/// ```rust
+/// use tower_layer::Identity;
+/// use tower_layer::Layer;
+///
+/// let identity = Identity::new();
+///
+/// assert_eq!(identity.layer(42), 42);
+/// ```
 #[derive(Default, Clone)]
 pub struct Identity {
     _p: (),
 }
 
 impl Identity {
-    /// Create a new [`Identity`] value
+    /// Creates a new [`Identity`].
+    ///
+    /// ```rust
+    /// use tower_layer::Identity;
+    ///
+    /// let identity = Identity::new();
+    /// ```
     pub const fn new() -> Identity {
         Identity { _p: () }
     }
 }
 
-/// Decorates a [`Service`], transforming either the request or the response.
-///
-/// [`Service`]: https://docs.rs/tower-service/latest/tower_service/trait.Service.html
 impl<S> Layer<S> for Identity {
     type Service = S;
 

tower-layer/src/layer_fn.rs

@@ -4,13 +4,17 @@ use core::fmt;
 /// Returns a new [`LayerFn`] that implements [`Layer`] by calling the
 /// given function.
 ///
-/// The [`Layer::layer`] method takes a type implementing [`Service`] and
+/// The [`Layer::layer()`] method takes a type implementing [`Service`] and
 /// returns a different type implementing [`Service`]. In many cases, this can
 /// be implemented by a function or a closure. The [`LayerFn`] helper allows
 /// writing simple [`Layer`] implementations without needing the boilerplate of
 /// a new struct implementing [`Layer`].
 ///
-/// # Example
+/// [`Service`]: https://docs.rs/tower-service/latest/tower_service/trait.Service.html
+/// [`Layer::layer()`]: crate::Layer::layer
+///
+/// # Examples
+///
 /// ```rust
 /// # use tower::Service;
 /// # use core::task::{Poll, Context};
@@ -61,9 +65,6 @@ use core::fmt;
 /// // Wrap our service in a `LogService` so requests are logged.
 /// let wrapped_service = log_layer.layer(uppercase_service);
 /// ```
-///
-/// [`Service`]: https://docs.rs/tower-service/latest/tower_service/trait.Service.html
-/// [`Layer::layer`]: crate::Layer::layer
 pub fn layer_fn<T>(f: T) -> LayerFn<T> {
     LayerFn { f }
 }

tower-layer/src/stack.rs

@@ -1,15 +1,38 @@
 use super::Layer;
 use core::fmt;
 
-/// Two middlewares chained together.
+/// Two [`Layer`]s chained together.
+///
+/// # Examples
+///
+/// ```rust
+/// use tower_layer::{Stack, layer_fn, Layer};
+///
+/// let inner = layer_fn(|service| service+2);
+/// let outer = layer_fn(|service| service*2);
+///
+/// let inner_outer_stack = Stack::new(inner, outer);
+///
+/// // (4 + 2) * 2 = 12
+/// // (4 * 2) + 2 = 10
+/// assert_eq!(inner_outer_stack.layer(4), 12);
+/// ```
 #[derive(Clone)]
 pub struct Stack<Inner, Outer> {
     inner: Inner,
     outer: Outer,
 }
 
 impl<Inner, Outer> Stack<Inner, Outer> {
-    /// Create a new `Stack`.
+    /// Creates a new [`Stack`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use tower_layer::{Stack, Identity};
+    ///
+    /// let stack = Stack::new(Identity::new(), Identity::new());
+    /// ```
     pub const fn new(inner: Inner, outer: Outer) -> Self {
         Stack { inner, outer }
     }