Fix broken links in documentation

tower-rs · Jul 19, 2023 · d042a2a · d042a2a
1 parent 23de275
commit d042a2a
Show file tree

Hide file tree

Showing 3 changed files with 79 additions and 81 deletions.
diff --git a/tower-http/src/timeout/body.rs b/tower-http/src/timeout/body.rs
@@ -1,40 +1,3 @@
-//! Middleware that applies a timeout to request and response bodies.
-//!
-//! Bodies must produce data at most within the specified timeout.
-//! If the body does not produce a requested data frame within the timeout period, it will return an error.
-//!
-//! # Differences from [`crate::timeout::Timeout`]
-//!
-//! [`crate::timeout::Timeout`] applies a timeout to the request future, not body.
-//! That timeout is not reset when bytes are handled, whether the request is active or not.
-//! Bodies are handled asynchronously outside of the tower stack's future and thus needs an additional timeout.
-//!
-//! This middleware will return a [`TimeoutError`].
-//!
-//! # Example
-//!
-//! ```
-//! use http::{Request, Response};
-//! use hyper::Body;
-//! use std::time::Duration;
-//! use tower::ServiceBuilder;
-//! use tower_http::timeout::RequestBodyTimeoutLayer;
-//!
-//! async fn handle(_: Request<Body>) -> Result<Response<Body>, std::convert::Infallible> {
-//!     // ...
-//!     # todo!()
-//! }
-//!
-//! # #[tokio::main]
-//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
-//! let svc = ServiceBuilder::new()
-//!     // Timeout bodies after 30 seconds of inactivity
-//!     .layer(RequestBodyTimeoutLayer::new(Duration::from_secs(30)))
-//!     .service_fn(handle);
-//! # Ok(())
-//! # }
-//! ```
-
 use crate::BoxError;
 use futures_core::{ready, Future};
 use http_body::Body;
@@ -47,7 +10,44 @@ use std::{
 use tokio::time::{sleep, Sleep};
 
 pin_project! {
+    /// Middleware that applies a timeout to request and response bodies.
+    ///
     /// Wrapper around a [`http_body::Body`] to time out if data is not ready within the specified duration.
+    ///
+    /// Bodies must produce data at most within the specified timeout.
+    /// If the body does not produce a requested data frame within the timeout period, it will return an error.
+    ///
+    /// # Differences from [`Timeout`][crate::timeout::Timeout]
+    ///
+    /// [`Timeout`][crate::timeout::Timeout] applies a timeout to the request future, not body.
+    /// That timeout is not reset when bytes are handled, whether the request is active or not.
+    /// Bodies are handled asynchronously outside of the tower stack's future and thus needs an additional timeout.
+    ///
+    /// This middleware will return a [`TimeoutError`].
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use http::{Request, Response};
+    /// use hyper::Body;
+    /// use std::time::Duration;
+    /// use tower::ServiceBuilder;
+    /// use tower_http::timeout::RequestBodyTimeoutLayer;
+    ///
+    /// async fn handle(_: Request<Body>) -> Result<Response<Body>, std::convert::Infallible> {
+    ///     // ...
+    ///     # todo!()
+    /// }
+    ///
+    /// # #[tokio::main]
+    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// let svc = ServiceBuilder::new()
+    ///     // Timeout bodies after 30 seconds of inactivity
+    ///     .layer(RequestBodyTimeoutLayer::new(Duration::from_secs(30)))
+    ///     .service_fn(handle);
+    /// # Ok(())
+    /// # }
+    /// ```
     pub struct TimeoutBody<B> {
         timeout: Duration,
         // In http-body 1.0, `poll_*` will be merged into `poll_frame`.

diff --git a/tower-http/src/timeout/mod.rs b/tower-http/src/timeout/mod.rs
@@ -1,4 +1,43 @@
-//! Middleware for setting timeouts on requests and responses.
+//! Middleware that applies a timeout to requests.
+//!
+//! If the request does not complete within the specified timeout it will be aborted and a `408
+//! Request Timeout` response will be sent.
+//!
+//! # Differences from `tower::timeout`
+//!
+//! tower's [`Timeout`](tower::timeout::Timeout) middleware uses an error to signal timeout, i.e.
+//! it changes the error type to [`BoxError`](tower::BoxError). For HTTP services that is rarely
+//! what you want as returning errors will terminate the connection without sending a response.
+//!
+//! This middleware won't change the error type and instead return a `408 Request Timeout`
+//! response. That means if your service's error type is [`Infallible`] it will still be
+//! [`Infallible`] after applying this middleware.
+//!
+//! # Example
+//!
+//! ```
+//! use http::{Request, Response};
+//! use hyper::Body;
+//! use std::{convert::Infallible, time::Duration};
+//! use tower::ServiceBuilder;
+//! use tower_http::timeout::TimeoutLayer;
+//!
+//! async fn handle(_: Request<Body>) -> Result<Response<Body>, Infallible> {
+//!     // ...
+//!     # Ok(Response::new(Body::empty()))
+//! }
+//!
+//! # #[tokio::main]
+//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! let svc = ServiceBuilder::new()
+//!     // Timeout requests after 30 seconds
+//!     .layer(TimeoutLayer::new(Duration::from_secs(30)))
+//!     .service_fn(handle);
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! [`Infallible`]: std::convert::Infallible
 
 mod body;
 mod service;

diff --git a/tower-http/src/timeout/service.rs b/tower-http/src/timeout/service.rs
@@ -1,44 +1,3 @@
-//! Middleware that applies a timeout to requests.
-//!
-//! If the request does not complete within the specified timeout it will be aborted and a `408
-//! Request Timeout` response will be sent.
-//!
-//! # Differences from `tower::timeout`
-//!
-//! tower's [`Timeout`](tower::timeout::Timeout) middleware uses an error to signal timeout, i.e.
-//! it changes the error type to [`BoxError`](tower::BoxError). For HTTP services that is rarely
-//! what you want as returning errors will terminate the connection without sending a response.
-//!
-//! This middleware won't change the error type and instead return a `408 Request Timeout`
-//! response. That means if your service's error type is [`Infallible`] it will still be
-//! [`Infallible`] after applying this middleware.
-//!
-//! # Example
-//!
-//! ```
-//! use http::{Request, Response};
-//! use hyper::Body;
-//! use std::{convert::Infallible, time::Duration};
-//! use tower::ServiceBuilder;
-//! use tower_http::timeout::TimeoutLayer;
-//!
-//! async fn handle(_: Request<Body>) -> Result<Response<Body>, Infallible> {
-//!     // ...
-//!     # Ok(Response::new(Body::empty()))
-//! }
-//!
-//! # #[tokio::main]
-//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
-//! let svc = ServiceBuilder::new()
-//!     // Timeout requests after 30 seconds
-//!     .layer(TimeoutLayer::new(Duration::from_secs(30)))
-//!     .service_fn(handle);
-//! # Ok(())
-//! # }
-//! ```
-//!
-//! [`Infallible`]: std::convert::Infallible
-
 use crate::timeout::body::TimeoutBody;
 use futures_core::ready;
 use http::{Request, Response, StatusCode};
@@ -55,7 +14,7 @@ use tower_service::Service;
 
 /// Layer that applies the [`Timeout`] middleware which apply a timeout to requests.
 ///
-/// See the [module docs](self) for an example.
+/// See the [module docs](super) for an example.
 #[derive(Debug, Clone, Copy)]
 pub struct TimeoutLayer {
     timeout: Duration,
@@ -81,7 +40,7 @@ impl<S> Layer<S> for TimeoutLayer {
 /// If the request does not complete within the specified timeout it will be aborted and a `408
 /// Request Timeout` response will be sent.
 ///
-/// See the [module docs](self) for an example.
+/// See the [module docs](super) for an example.
 #[derive(Debug, Clone, Copy)]
 pub struct Timeout<S> {
     inner: S,