diff --git a/src/lib.rs b/src/lib.rs index a67c722f7..5b8ef56ac 100755 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,7 +5,8 @@ nonstandard_style, rust_2018_idioms, future_incompatible, - missing_debug_implementations + missing_debug_implementations, + missing_docs )] //! @@ -41,6 +42,8 @@ pub use tide_core::{ }; pub mod error { + //! Module to export tide_core errors + pub use tide_core::error::{ EndpointResult, Error, ResponseExt, ResultDynErrExt, ResultExt, StringError, }; @@ -50,6 +53,8 @@ pub use tide_forms as forms; pub use tide_querystring as querystring; pub mod middleware { + //! Module to export tide_core middleware + // Core pub use tide_core::middleware::{Middleware, Next}; diff --git a/tide-compression/src/lib.rs b/tide-compression/src/lib.rs index 721caa9bb..07c3c78ee 100644 --- a/tide-compression/src/lib.rs +++ b/tide-compression/src/lib.rs @@ -8,9 +8,12 @@ nonstandard_style, rust_2018_idioms, future_incompatible, - missing_debug_implementations + missing_debug_implementations, + missing_docs )] +//! Compression-related middleware for Tide + pub use accept_encoding::Encoding; use async_compression::stream; use futures::future::BoxFuture; diff --git a/tide-cookies/src/lib.rs b/tide-cookies/src/lib.rs index 128b2d923..c1c72a651 100644 --- a/tide-cookies/src/lib.rs +++ b/tide-cookies/src/lib.rs @@ -6,9 +6,12 @@ nonstandard_style, rust_2018_idioms, future_incompatible, - missing_debug_implementations + missing_debug_implementations, + missing_docs )] +//! Cookie management for Tide web framework + mod data; mod middleware; diff --git a/tide-cookies/src/middleware.rs b/tide-cookies/src/middleware.rs index 9c34ff332..41c3e10db 100644 --- a/tide-cookies/src/middleware.rs +++ b/tide-cookies/src/middleware.rs @@ -10,17 +10,21 @@ use tide_core::{ /// Middleware to work with cookies. /// -/// [`CookiesMiddleware`] along with [`ContextExt`](crate::data::ContextExt) provide smooth +/// [`CookiesMiddleware`] along with [`ContextExt`] provide smooth /// access to request cookies and setting/removing cookies from response. This leverages the /// [cookie](https://crates.io/crates/cookie) crate. /// This middleware parses cookies from request and caches them in the extension. Once the request /// is processed by endpoints and other middlewares, all the added and removed cookies are set on /// on the response. You will need to add this middle before any other middlewares that might need /// to access Cookies. +/// +/// [`CookiesMiddleware`]: crate::middleware::CookiesMiddleware +/// [`ContextExt`]: ../../tide/cookies/trait.ContextExt.html #[derive(Clone, Default, Debug)] pub struct CookiesMiddleware {} impl CookiesMiddleware { + /// CookieMiddleware constructor pub fn new() -> Self { Self {} } diff --git a/tide-core/src/app.rs b/tide-core/src/app.rs index 181ef649e..b036fb0d0 100644 --- a/tide-core/src/app.rs +++ b/tide-core/src/app.rs @@ -220,6 +220,8 @@ impl App { /// /// Middleware can only be added at the "top level" of an application, /// and is processed in the order in which it is applied. + /// + /// [`Middleware`]: crate::middleware::Middleware pub fn middleware(&mut self, m: impl Middleware) -> &mut Self { self.middleware.push(Arc::new(m)); self @@ -270,6 +272,8 @@ impl App { /// /// This type is useful only in conjunction with the [`HttpService`] trait, /// i.e. for hosting a Tide app within some custom HTTP server. +/// +/// [`HttpService`]: http_service::HttpService #[derive(Clone)] #[allow(missing_debug_implementations)] pub struct Server { diff --git a/tide-core/src/endpoint.rs b/tide-core/src/endpoint.rs index c7959b469..2b379295c 100644 --- a/tide-core/src/endpoint.rs +++ b/tide-core/src/endpoint.rs @@ -9,7 +9,7 @@ use crate::{response::IntoResponse, Context, Response}; /// directly by Tide users. /// /// In practice, endpoints are functions that take a `Context` as an argument and -/// return a type `T` that implements [`IntoResponse`]. +/// return a type `T` that implements [`IntoResponse`](crate::response::IntoResponse). /// /// # Examples /// diff --git a/tide-core/src/error.rs b/tide-core/src/error.rs index a64f53edd..5062939ca 100644 --- a/tide-core/src/error.rs +++ b/tide-core/src/error.rs @@ -1,9 +1,11 @@ -use http::{HttpTryFrom, Response, StatusCode}; -use http_service::Body; +//! Error and Result module use crate::response::IntoResponse; +use http::{HttpTryFrom, Response, StatusCode}; +use http_service::Body; #[derive(Debug)] +/// A string error, which can be display pub struct StringError(pub String); impl std::error::Error for StringError {} @@ -14,6 +16,7 @@ impl std::fmt::Display for StringError { } #[macro_export] +/// Macro that generates StringError immediately macro_rules! err_fmt { {$($t:tt)*} => { $crate::error::StringError(format!($($t)*)) diff --git a/tide-core/src/lib.rs b/tide-core/src/lib.rs index ecdf21390..4ede67a03 100644 --- a/tide-core/src/lib.rs +++ b/tide-core/src/lib.rs @@ -5,12 +5,19 @@ nonstandard_style, rust_2018_idioms, future_incompatible, - missing_debug_implementations + missing_debug_implementations, + missing_docs )] // TODO: Remove this after clippy bug due to async await is resolved. // ISSUE: https://github.com/rust-lang/rust-clippy/issues/3988 #![allow(clippy::needless_lifetimes)] +//! +//! Tide core api document +//! +//! The [`App`] docs are a good place to get started. +//! + mod app; mod context; mod endpoint; diff --git a/tide-core/src/middleware.rs b/tide-core/src/middleware.rs index 2b881f27f..12129edd0 100644 --- a/tide-core/src/middleware.rs +++ b/tide-core/src/middleware.rs @@ -1,6 +1,7 @@ +//! Middlewares + use crate::{endpoint::DynEndpoint, Context, Response}; use futures::future::BoxFuture; - use std::sync::Arc; /// Middleware that wraps around remaining middleware chain. diff --git a/tide-core/src/response.rs b/tide-core/src/response.rs index 90751b25d..0adea7e63 100644 --- a/tide-core/src/response.rs +++ b/tide-core/src/response.rs @@ -1,5 +1,8 @@ +//! Multiple types of response modules + use http_service::Body; +/// An Http response pub type Response = http_service::Response; /// Serialize `t` into a JSON-encoded response. diff --git a/tide-core/src/route.rs b/tide-core/src/route.rs index 0406e793a..dc5297073 100644 --- a/tide-core/src/route.rs +++ b/tide-core/src/route.rs @@ -37,6 +37,7 @@ impl<'a, State: 'static> Route<'a, State> { } } + /// Add endpoint nested routes pub fn nest(&mut self, f: impl FnOnce(&mut Route<'a, State>)) -> &mut Self { f(self); self diff --git a/tide-querystring/src/lib.rs b/tide-querystring/src/lib.rs index 48023f061..15e735a7f 100644 --- a/tide-querystring/src/lib.rs +++ b/tide-querystring/src/lib.rs @@ -15,6 +15,7 @@ use tide_core::{error::Error, Context}; /// An extension trait for `Context`, providing query string deserialization. pub trait ContextExt<'de> { + /// Analyze url and extract query parameters fn url_query>(&'de self) -> Result; }