From d0d6ed54cf4d40a44ae9c7011c057576e522c2ed Mon Sep 17 00:00:00 2001
From: Sean McArthur <sean@seanmonstar.com>
Date: Tue, 23 Apr 2019 13:42:56 -0700
Subject: [PATCH] unify/improve style of docs shown by facade

---
 tower-limit/src/concurrency/future.rs  | 1 +
 tower-limit/src/concurrency/layer.rs   | 3 +++
 tower-limit/src/concurrency/mod.rs     | 4 ++--
 tower-limit/src/concurrency/service.rs | 4 +++-
 tower-limit/src/lib.rs                 | 6 +++++-
 tower-limit/src/rate/future.rs         | 1 +
 tower-limit/src/rate/layer.rs          | 3 +++
 tower-limit/src/rate/mod.rs            | 4 ++--
 tower-limit/src/rate/rate.rs           | 3 ++-
 tower-limit/src/rate/service.rs        | 2 ++
 tower-load-shed/src/lib.rs             | 2 +-
 tower-service/src/lib.rs               | 7 ++-----
 tower/src/lib.rs                       | 8 ++++++--
 13 files changed, 33 insertions(+), 15 deletions(-)

diff --git a/tower-limit/src/concurrency/future.rs b/tower-limit/src/concurrency/future.rs
index 97c07219..209ef773 100644
--- a/tower-limit/src/concurrency/future.rs
+++ b/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,
diff --git a/tower-limit/src/concurrency/layer.rs b/tower-limit/src/concurrency/layer.rs
index 24b0e818..68ecd810 100644
--- a/tower-limit/src/concurrency/layer.rs
+++ b/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 }
     }
diff --git a/tower-limit/src/concurrency/mod.rs b/tower-limit/src/concurrency/mod.rs
index 467514eb..91cde3bb 100644
--- a/tower-limit/src/concurrency/mod.rs
+++ b/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>;
diff --git a/tower-limit/src/concurrency/service.rs b/tower-limit/src/concurrency/service.rs
index bd201cb6..80884fcc 100644
--- a/tower-limit/src/concurrency/service.rs
+++ b/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,
diff --git a/tower-limit/src/lib.rs b/tower-limit/src/lib.rs
index 814342b6..62acf337 100644
--- a/tower-limit/src/lib.rs
+++ b/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;
diff --git a/tower-limit/src/rate/future.rs b/tower-limit/src/rate/future.rs
index 8be1c1cd..de149c43 100644
--- a/tower-limit/src/rate/future.rs
+++ b/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,
diff --git a/tower-limit/src/rate/layer.rs b/tower-limit/src/rate/layer.rs
index c4157f14..61ea092e 100644
--- a/tower-limit/src/rate/layer.rs
+++ b/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 }
diff --git a/tower-limit/src/rate/mod.rs b/tower-limit/src/rate/mod.rs
index e87bd2f3..0e4b9f5c 100644
--- a/tower-limit/src/rate/mod.rs
+++ b/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};
diff --git a/tower-limit/src/rate/rate.rs b/tower-limit/src/rate/rate.rs
index 9e57e364..d0736f42 100644
--- a/tower-limit/src/rate/rate.rs
+++ b/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
     ///
diff --git a/tower-limit/src/rate/service.rs b/tower-limit/src/rate/service.rs
index a5bfb57e..ef4427ec 100644
--- a/tower-limit/src/rate/service.rs
+++ b/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,
diff --git a/tower-load-shed/src/lib.rs b/tower-load-shed/src/lib.rs
index ef7a9870..f812da3d 100644
--- a/tower-load-shed/src/lib.rs
+++ b/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;
diff --git a/tower-service/src/lib.rs b/tower-service/src/lib.rs
index 896804f3..87b881e3 100644
--- a/tower-service/src/lib.rs
+++ b/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 /
-//! response clients and servers. They are simple but powerul and are
+//! The [`Service`] trait provides the necessary abstractions for defining a
+//! 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;
 
diff --git a/tower/src/lib.rs b/tower/src/lib.rs
index 465433a9..e639c9f4 100644
--- a/tower/src/lib.rs
+++ b/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;