Improve server document and others

crates/core/src/conn/unix.rs

@@ -7,7 +7,6 @@ use std::time::Duration;
 
 use http::uri::Scheme;
 use tokio::net::{UnixListener as TokioUnixListener, UnixStream};
-use tokio_util::sync::CancellationToken;        
 use nix::unistd::{Gid, chown, Uid};    
 
 use crate::async_trait;

crates/core/src/handler.rs

@@ -38,6 +38,8 @@ use crate::http::StatusCode;
 use crate::{async_trait, Depot, FlowCtrl, Request, Response};
 
 /// Handler
+/// 
+/// `Handler` is used for handle [`Request`]. View [module level documentation](index.html) for more details.
 #[async_trait]
 pub trait Handler: Send + Sync + 'static {
     #[doc(hidden)]
@@ -88,6 +90,8 @@ where
     }
 }
 
+/// `Skipper` is used to check if the request should be skipped.
+/// 
 /// `Skipper` is used in many middlewares.
 pub trait Skipper: Send + Sync + 'static {
     /// Check if the request should be skipped.

crates/core/src/http/body/channel.rs

@@ -7,7 +7,7 @@ use bytes::Bytes;
 use futures_channel::{mpsc, oneshot};
 use hyper::HeaderMap;
 
-/// A sender half created through [`ResBody::channel()`].
+/// A sender half created through [`ResBody ::Channel`].
 ///
 /// Useful when wanting to stream chunks from another thread.
 ///
@@ -154,7 +154,7 @@ impl fmt::Debug for BodySender {
     }
 }
 
-/// A receiver for [`ResBody`]
+/// A receiver for [`ResBody`](super::ResBody).
 pub struct BodyReceiver {
     pub(crate) data_rx: mpsc::Receiver<Result<Bytes, IoError>>,
     pub(crate) trailers_rx: oneshot::Receiver<HeaderMap>,

crates/core/src/lib.rs

@@ -33,7 +33,7 @@ pub mod routing;
 pub mod rt;
 #[doc(hidden)]
 pub mod serde;
-mod server;
+pub mod server;
 mod service;
 pub mod writing;
 cfg_feature! {

crates/core/src/server.rs

@@ -26,10 +26,40 @@ pub struct ServerHandle {
 
 impl ServerHandle {
     /// Force stop server.
+    ///
+    /// Call this function will stop server immediately.
     pub fn stop_forcible(&self) {
         self.tx_cmd.send(ServerCommand::StopForcible).ok();
     }
     /// Graceful stop server.
+    ///
+    /// Call this function will stop server after all connections are closed,
+    /// allowing it to finish processing any ongoing requests before terminating. 
+    /// It ensures that all connections are closed properly and any resources are released.
+    /// 
+    /// You can specify a timeout to force stop server. 
+    /// If `timeout` is `None`, it will wait util all connections are closed.
+    ///
+    /// This function gracefully stop the server, allowing it to finish processing any
+    /// ongoing requests before terminating. It ensures that all connections are closed
+    /// properly and any resources are released.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use salvo_core::prelude::*;
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let acceptor = TcpListener::new("127.0.0.1:5800").bind().await;
+    ///     let server = Server::new(acceptor);
+    ///     let handle = server.handle();
+    ///
+    ///     // Gracefully shut down the server
+    ///     handle.stop_graceful(None);
+    /// }
+    /// ```
+    /// 
     pub fn stop_graceful(&self, timeout: impl Into<Option<Duration>>) {
         self.tx_cmd.send(ServerCommand::StopGraceful(timeout.into())).ok();
     }
@@ -57,13 +87,13 @@ impl<A: Acceptor + Send> Server<A> {
     /// # Example
     ///
     /// ```no_run
-    /// # use salvo_core::prelude::*;
+    /// use salvo_core::prelude::*;
     ///
-    /// # #[tokio::main]
-    /// # async fn main() {
-    /// let acceptor = TcpListener::new("127.0.0.1:5800").bind().await;
-    /// Server::new(acceptor);
-    /// # }
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let acceptor = TcpListener::new("127.0.0.1:5800").bind().await;
+    ///     Server::new(acceptor);
+    /// }
     /// ```
     pub fn new(acceptor: A) -> Self {
         Self::with_http_builder(
@@ -99,10 +129,17 @@ impl<A: Acceptor + Send> Server<A> {
     }
 
     /// Force stop server.
+    ///
+    /// Call this function will stop server immediately.
     pub fn stop_forcible(&self) {
         self.tx_cmd.send(ServerCommand::StopForcible).ok();
     }
+
     /// Graceful stop server.
+    ///
+    /// Call this function will stop server after all connections are closed.
+    /// You can specify a timeout to force stop server. 
+    /// If `timeout` is `None`, it will wait util all connections are closed.
     pub fn stop_graceful(&self, timeout: impl Into<Option<Duration>>) {
         self.tx_cmd.send(ServerCommand::StopGraceful(timeout.into())).ok();
     }
@@ -145,7 +182,25 @@ impl<A: Acceptor + Send> Server<A> {
         self
     }
 
-    /// Serve a [`Service`]
+    /// Serve a [`Service`].
+    /// 
+    /// # Example
+    ///
+    /// ```no_run
+    /// use salvo_core::prelude::*;
+
+    /// #[handler]
+    /// async fn hello() -> &'static str {
+    ///     "Hello World"
+    /// }
+    /// 
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let acceptor = TcpListener::new("0.0.0.0:5800").bind().await;
+    ///     let router = Router::new().get(hello);
+    ///     Server::new(acceptor).serve(router).await;
+    /// }
+    /// ```
     #[inline]
     pub async fn serve<S>(self, service: S)
     where
@@ -154,7 +209,7 @@ impl<A: Acceptor + Send> Server<A> {
         self.try_serve(service).await.unwrap();
     }
 
-    /// Try to serve a [`Service`]
+    /// Try to serve a [`Service`].
     #[inline]
     pub async fn try_serve<S>(self, service: S) -> IoResult<()>
     where
@@ -215,7 +270,7 @@ impl<A: Acceptor + Send> Server<A> {
                     }
                     break;
                 },
-                 accepted = acceptor.accept() => {
+                accepted = acceptor.accept() => {
                     match accepted {
                         Ok(Accepted { conn, local_addr, remote_addr, http_scheme, ..}) => {
                             alive_connections.fetch_add(1, Ordering::Release);

examples/oapi-todos/README.md

@@ -10,4 +10,4 @@ and then try:
 
 http://0.0.0.0:5800/api-doc/openapi.json
 
-http://0.0.0.0:5800/swagger-ui/
+http://0.0.0.0:5800/