From 5d532641fcbde4e81253688abeebe9ee2f510b93 Mon Sep 17 00:00:00 2001 From: k-nasa Date: Tue, 21 May 2019 10:16:10 +0900 Subject: [PATCH 1/7] doc: Add doc comment to tide-core --- tide-core/src/endpoint.rs | 2 +- tide-core/src/error.rs | 7 +++++-- tide-core/src/lib.rs | 9 ++++++++- tide-core/src/middleware.rs | 3 ++- tide-core/src/response.rs | 3 +++ tide-core/src/route.rs | 6 ++++++ 6 files changed, 25 insertions(+), 5 deletions(-) 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..1d65c0696 100644 --- a/tide-core/src/route.rs +++ b/tide-core/src/route.rs @@ -37,6 +37,12 @@ impl<'a, State: 'static> Route<'a, State> { } } + /// Add endpoint nested routes as in the example + ///```rust, no_run + /// router.at("/b").nest(|router| { + /// router.at("/").get(async move |_| "/b"); + /// router.at("/a").get(async move |_| "/b/a"); + ///``` pub fn nest(&mut self, f: impl FnOnce(&mut Route<'a, State>)) -> &mut Self { f(self); self From 174704714e6f4dfc32df3c16f68f9e0d91be6484 Mon Sep 17 00:00:00 2001 From: k-nasa Date: Tue, 21 May 2019 10:21:44 +0900 Subject: [PATCH 2/7] doc: Add documantation to tide-cookie --- tide-cookies/src/lib.rs | 5 ++++- tide-cookies/src/middleware.rs | 1 + 2 files changed, 5 insertions(+), 1 deletion(-) 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..b88ef1bfa 100644 --- a/tide-cookies/src/middleware.rs +++ b/tide-cookies/src/middleware.rs @@ -21,6 +21,7 @@ use tide_core::{ pub struct CookiesMiddleware {} impl CookiesMiddleware { + /// CookieMiddleware constructor pub fn new() -> Self { Self {} } From c55b38822349446613e101fe7932f3d0e86155c4 Mon Sep 17 00:00:00 2001 From: k-nasa Date: Tue, 21 May 2019 11:08:38 +0900 Subject: [PATCH 3/7] doc: Add doc to tide-compression --- tide-compression/src/lib.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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; From 58daacc4a4f77cd6f6073e01ac1440d460fadef1 Mon Sep 17 00:00:00 2001 From: k-nasa Date: Tue, 21 May 2019 11:09:07 +0900 Subject: [PATCH 4/7] doc: Add doc comment --- src/error.rs | 10 ++++++++++ src/lib.rs | 3 ++- src/middleware.rs | 11 +++++++++++ tide-core/src/route.rs | 6 +++--- tide-querystring/src/lib.rs | 1 + 5 files changed, 27 insertions(+), 4 deletions(-) create mode 100644 src/error.rs create mode 100644 src/middleware.rs diff --git a/src/error.rs b/src/error.rs new file mode 100644 index 000000000..255e35ac9 --- /dev/null +++ b/src/error.rs @@ -0,0 +1,10 @@ +//! Module to export tide_core errors + +use core::pin::Pin; +use futures::future::Future; + +pub use tide_core::error::{ + EndpointResult, Error, ResponseExt, ResultDynErrExt, ResultExt, StringError, +}; + +pub(crate) type BoxTryFuture = Pin> + Send + 'static>>; diff --git a/src/lib.rs b/src/lib.rs index a67c722f7..9c0837d1f 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 )] //! diff --git a/src/middleware.rs b/src/middleware.rs new file mode 100644 index 000000000..9146a642f --- /dev/null +++ b/src/middleware.rs @@ -0,0 +1,11 @@ +//! Middlewares + +// Core +pub use tide_core::middleware::{Middleware, Next}; + +// Exports from tide repo. +pub use tide_headers::DefaultHeaders; +pub use tide_log::RequestLogger; + +#[cfg(feature = "cookies")] +pub use tide_cookies::CookiesMiddleware; diff --git a/tide-core/src/route.rs b/tide-core/src/route.rs index 1d65c0696..6583862e2 100644 --- a/tide-core/src/route.rs +++ b/tide-core/src/route.rs @@ -39,9 +39,9 @@ impl<'a, State: 'static> Route<'a, State> { /// Add endpoint nested routes as in the example ///```rust, no_run - /// router.at("/b").nest(|router| { - /// router.at("/").get(async move |_| "/b"); - /// router.at("/a").get(async move |_| "/b/a"); + /// router.at("/a").nest(|router| { + /// router.at("/").get(async move |_| "/a"); + /// router.at("/b").get(async move |_| "/a/b"); ///``` pub fn nest(&mut self, f: impl FnOnce(&mut Route<'a, State>)) -> &mut Self { f(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; } From 3d0e0c7343c2958edb8cf8d4590ee30b014121e4 Mon Sep 17 00:00:00 2001 From: k-nasa Date: Tue, 21 May 2019 13:59:57 +0900 Subject: [PATCH 5/7] fix doc links --- tide-cookies/src/middleware.rs | 5 ++++- tide-core/src/app.rs | 4 ++++ tide-core/src/route.rs | 7 +------ 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/tide-cookies/src/middleware.rs b/tide-cookies/src/middleware.rs index b88ef1bfa..e137c6a32 100644 --- a/tide-cookies/src/middleware.rs +++ b/tide-cookies/src/middleware.rs @@ -10,13 +10,16 @@ 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`]: crate::data::ContextExt #[derive(Clone, Default, Debug)] pub struct CookiesMiddleware {} 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/route.rs b/tide-core/src/route.rs index 6583862e2..dc5297073 100644 --- a/tide-core/src/route.rs +++ b/tide-core/src/route.rs @@ -37,12 +37,7 @@ impl<'a, State: 'static> Route<'a, State> { } } - /// Add endpoint nested routes as in the example - ///```rust, no_run - /// router.at("/a").nest(|router| { - /// router.at("/").get(async move |_| "/a"); - /// router.at("/b").get(async move |_| "/a/b"); - ///``` + /// Add endpoint nested routes pub fn nest(&mut self, f: impl FnOnce(&mut Route<'a, State>)) -> &mut Self { f(self); self From 8519e4e99b9f1ff3d3e35a7c2f2c2a5ddc29cdac Mon Sep 17 00:00:00 2001 From: k-nasa Date: Tue, 21 May 2019 15:32:24 +0900 Subject: [PATCH 6/7] fix path --- tide-cookies/src/middleware.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tide-cookies/src/middleware.rs b/tide-cookies/src/middleware.rs index e137c6a32..41c3e10db 100644 --- a/tide-cookies/src/middleware.rs +++ b/tide-cookies/src/middleware.rs @@ -19,7 +19,7 @@ use tide_core::{ /// to access Cookies. /// /// [`CookiesMiddleware`]: crate::middleware::CookiesMiddleware -/// [`ContextExt`]: crate::data::ContextExt +/// [`ContextExt`]: ../../tide/cookies/trait.ContextExt.html #[derive(Clone, Default, Debug)] pub struct CookiesMiddleware {} From 8c35b7c97a5b8bae8c8e994dac627e4ed7a44c92 Mon Sep 17 00:00:00 2001 From: k-nasa Date: Sat, 25 May 2019 08:56:02 +0900 Subject: [PATCH 7/7] doc: Add doc comment --- src/error.rs | 10 ---------- src/lib.rs | 4 ++++ src/middleware.rs | 11 ----------- 3 files changed, 4 insertions(+), 21 deletions(-) delete mode 100644 src/error.rs delete mode 100644 src/middleware.rs diff --git a/src/error.rs b/src/error.rs deleted file mode 100644 index 255e35ac9..000000000 --- a/src/error.rs +++ /dev/null @@ -1,10 +0,0 @@ -//! Module to export tide_core errors - -use core::pin::Pin; -use futures::future::Future; - -pub use tide_core::error::{ - EndpointResult, Error, ResponseExt, ResultDynErrExt, ResultExt, StringError, -}; - -pub(crate) type BoxTryFuture = Pin> + Send + 'static>>; diff --git a/src/lib.rs b/src/lib.rs index 9c0837d1f..5b8ef56ac 100755 --- a/src/lib.rs +++ b/src/lib.rs @@ -42,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, }; @@ -51,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/src/middleware.rs b/src/middleware.rs deleted file mode 100644 index 9146a642f..000000000 --- a/src/middleware.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Middlewares - -// Core -pub use tide_core::middleware::{Middleware, Next}; - -// Exports from tide repo. -pub use tide_headers::DefaultHeaders; -pub use tide_log::RequestLogger; - -#[cfg(feature = "cookies")] -pub use tide_cookies::CookiesMiddleware;