Add doc comment (#250)

* doc: Add doc comment to tide-core

* doc: Add documantation to tide-cookie

* doc: Add doc to tide-compression

* doc: Add doc comment

* fix doc links

* fix path

* doc: Add doc comment

Author: k-nasa

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};
 

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;

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;
 

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 {}
     }

tide-core/src/app.rs

@@ -220,6 +220,8 @@ impl<State: Send + Sync + 'static> App<State> {
     ///
     /// 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<State>) -> &mut Self {
         self.middleware.push(Arc::new(m));
         self
@@ -270,6 +272,8 @@ impl<State: Send + Sync + 'static> App<State> {
 ///
 /// 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<State> {

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<State>` as an argument and
-/// return a type `T` that implements [`IntoResponse`].
+/// return a type `T` that implements [`IntoResponse`](crate::response::IntoResponse).
 ///
 /// # Examples
 ///

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)*))

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;

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.

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.

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

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<T: Deserialize<'de>>(&'de self) -> Result<T, Error>;
 }