unify/improve style of docs shown by facade

tower-limit/src/concurrency/future.rs

@@ -3,6 +3,7 @@ use futures::{Future, Poll};
 use std::sync::Arc;
 use tokio_sync::semaphore::Semaphore;
 
+/// Future for the `ConcurrencyLimit` service.
 #[derive(Debug)]
 pub struct ResponseFuture<T> {
     inner: T,

tower-limit/src/concurrency/layer.rs

@@ -1,12 +1,15 @@
 use super::ConcurrencyLimit;
 use tower_layer::Layer;
 
+/// Enforces a limit on the concurrent number of requests the underlying
+/// service can handle.
 #[derive(Debug, Clone)]
 pub struct ConcurrencyLimitLayer {
     max: usize,
 }
 
 impl ConcurrencyLimitLayer {
+    /// Create a new concurrency limit layer.
     pub fn new(max: usize) -> Self {
         ConcurrencyLimitLayer { max }
     }

tower-limit/src/concurrency/mod.rs

@@ -1,9 +1,9 @@
 //! Limit the max number of requests being concurrently processed.
 
-pub mod future;
+mod future;
 mod layer;
 mod service;
 
-pub use self::{layer::ConcurrencyLimitLayer, service::ConcurrencyLimit};
+pub use self::{future::ResponseFuture, layer::ConcurrencyLimitLayer, service::ConcurrencyLimit};
 
 type Error = Box<dyn std::error::Error + Send + Sync>;

tower-limit/src/concurrency/service.rs

@@ -6,6 +6,8 @@ use futures::{try_ready, Poll};
 use std::sync::Arc;
 use tokio_sync::semaphore::{self, Semaphore};
 
+/// Enforces a limit on the concurrent number of requests the underlying
+/// service can handle.
 #[derive(Debug)]
 pub struct ConcurrencyLimit<T> {
     inner: T,
@@ -19,7 +21,7 @@ struct Limit {
 }
 
 impl<T> ConcurrencyLimit<T> {
-    /// Create a new rate limiter
+    /// Create a new concurrency limiter.
     pub fn new(inner: T, max: usize) -> Self {
         ConcurrencyLimit {
             inner,

tower-limit/src/lib.rs

@@ -1,6 +1,10 @@
+#![cfg_attr(test, deny(warnings))]
+#![deny(missing_debug_implementations)]
+#![deny(missing_docs)]
 #![deny(rust_2018_idioms)]
 #![allow(elided_lifetimes_in_paths)]
-//! Limit inbound requests.
+
+//! Tower middleware for limiting requests.
 
 pub mod concurrency;
 pub mod rate;

tower-limit/src/rate/future.rs

@@ -1,6 +1,7 @@
 use super::error::Error;
 use futures::{Future, Poll};
 
+/// Future for the `RateLimit` service.
 #[derive(Debug)]
 pub struct ResponseFuture<T> {
     inner: T,

tower-limit/src/rate/layer.rs

@@ -2,12 +2,15 @@ use super::{Rate, RateLimit};
 use std::time::Duration;
 use tower_layer::Layer;
 
+/// Enforces a rate limit on the number of requests the underlying
+/// service can handle over a period of time.
 #[derive(Debug)]
 pub struct RateLimitLayer {
     rate: Rate,
 }
 
 impl RateLimitLayer {
+    /// Create new rate limit layer.
     pub fn new(num: u64, per: Duration) -> Self {
         let rate = Rate::new(num, per);
         RateLimitLayer { rate }

tower-limit/src/rate/mod.rs

@@ -1,9 +1,9 @@
 //! Limit the rate at which requests are processed.
 
 mod error;
-pub mod future;
+mod future;
 mod layer;
 mod rate;
 mod service;
 
-pub use self::{layer::RateLimitLayer, rate::Rate, service::RateLimit};
+pub use self::{future::ResponseFuture, layer::RateLimitLayer, rate::Rate, service::RateLimit};

tower-limit/src/rate/rate.rs

@@ -1,5 +1,6 @@
 use std::time::Duration;
 
+/// A rate of requests per time period.
 #[derive(Debug, Copy, Clone)]
 pub struct Rate {
     num: u64,
@@ -7,7 +8,7 @@ pub struct Rate {
 }
 
 impl Rate {
-    /// Create a new rate
+    /// Create a new rate.
     ///
     /// # Panics
     ///

tower-limit/src/rate/service.rs

@@ -5,6 +5,8 @@ use tower_service::Service;
 
 use std::time::Instant;
 
+/// Enforces a rate limit on the number of requests the underlying
+/// service can handle over a period of time.
 #[derive(Debug)]
 pub struct RateLimit<T> {
     inner: T,

tower-load-shed/src/lib.rs

@@ -4,7 +4,7 @@
 #![deny(rust_2018_idioms)]
 #![allow(elided_lifetimes_in_paths)]
 
-//! tower-load-shed
+//! Tower middleware for shedding load when inner services aren't ready.
 
 use futures::Poll;
 use tower_service::Service;

tower-service/src/lib.rs

@@ -3,12 +3,9 @@
 
 //! Definition of the core `Service` trait to Tower
 //!
-//! These traits provide the necessary abstractions for defining a request /
+//! The [`Service`] trait provides the necessary abstractions for defining a
-//! response clients and servers. They are simple but powerul and are
+//! request / response clients and servers. It is simple but powerul and is
 //! used as the foundation for the rest of Tower.
-//!
-//! * [`Service`](trait.Service.html) is the primary trait and defines the request
-//! / response exchange. See that trait for more details.
 
 extern crate futures;
 

tower/src/lib.rs

@@ -1,9 +1,13 @@
 // Allows refining features in the future without breaking backwards
 // compatibility
 #![cfg(feature = "full")]
-#![deny(missing_docs, rust_2018_idioms)]
+#![deny(missing_docs, missing_debug_implementations, rust_2018_idioms)]
+#![cfg_attr(test, deny(warnings))]
 
-//! Various utility types and functions that are generally with Tower.
+//! `fn(Request) -> Future<Response>`
+//!
+//! Tower is a library of modular and reusable components for building
+//! robust networking clients and servers.
 
 #[doc(inline)]
 pub use tower_buffer as buffer;