refactor: improve cargo doc features

static-web-server · Jun 15, 2023 · 9e635bd · 9e635bd
1 parent 680c8aa
commit 9e635bd
Show file tree

Hide file tree

Showing 7 changed files with 29 additions and 2 deletions.
diff --git a/src/compression.rs b/src/compression.rs
@@ -115,6 +115,7 @@ pub fn auto(
 /// Create a wrapping handler that compresses the Body of a [`Response`](hyper::Response)
 /// using gzip, adding `content-encoding: gzip` to the Response's [`HeaderMap`](hyper::HeaderMap)
 #[cfg(feature = "compression-gzip")]
+#[cfg_attr(docsrs, doc(cfg(feature = "compression-gzip")))]
 pub fn gzip(
     mut head: http::response::Parts,
     body: CompressableBody<Body, hyper::Error>,
@@ -131,6 +132,7 @@ pub fn gzip(
 /// Create a wrapping handler that compresses the Body of a [`Response`](hyper::Response)
 /// using deflate, adding `content-encoding: deflate` to the Response's [`HeaderMap`](hyper::HeaderMap)
 #[cfg(feature = "compression-deflate")]
+#[cfg_attr(docsrs, doc(cfg(feature = "compression-deflate")))]
 pub fn deflate(
     mut head: http::response::Parts,
     body: CompressableBody<Body, hyper::Error>,
@@ -152,6 +154,7 @@ pub fn deflate(
 /// Create a wrapping handler that compresses the Body of a [`Response`](hyper::Response)
 /// using brotli, adding `content-encoding: br` to the Response's [`HeaderMap`](hyper::HeaderMap)
 #[cfg(feature = "compression-brotli")]
+#[cfg_attr(docsrs, doc(cfg(feature = "compression-brotli")))]
 pub fn brotli(
     mut head: http::response::Parts,
     body: CompressableBody<Body, hyper::Error>,
@@ -171,6 +174,7 @@ pub fn brotli(
 /// Create a wrapping handler that compresses the Body of a [`Response`](hyper::Response)
 /// using zstd, adding `content-encoding: zstd` to the Response's [`HeaderMap`](hyper::HeaderMap)
 #[cfg(feature = "compression-zstd")]
+#[cfg_attr(docsrs, doc(cfg(feature = "compression-zstd")))]
 pub fn zstd(
     mut head: http::response::Parts,
     body: CompressableBody<Body, hyper::Error>,

diff --git a/src/directory_listing.rs b/src/directory_listing.rs
@@ -6,8 +6,6 @@
 //! It provides directory listig and auto-index support.
 //!
 
-#![allow(missing_docs)]
-
 use chrono::{DateTime, Local, NaiveDateTime, Utc};
 use clap::ValueEnum;
 use futures_util::future::Either;
@@ -29,7 +27,9 @@ use crate::{exts::http::MethodExt, Context, Result};
 #[serde(rename_all = "lowercase")]
 /// Directory listing output format for file entries.
 pub enum DirListFmt {
+    /// HTML format to display (default).
     Html,
+    /// JSON format to display.
     Json,
 }
 

diff --git a/src/handler.rs b/src/handler.rs
@@ -42,11 +42,14 @@ pub struct RequestHandlerOpts {
     pub compression_static: bool,
     /// Directory listing feature.
     #[cfg(feature = "directory-listing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "directory-listing")))]
     pub dir_listing: bool,
     /// Directory listing order feature.
     #[cfg(feature = "directory-listing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "directory-listing")))]
     pub dir_listing_order: u8,
     #[cfg(feature = "directory-listing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "directory-listing")))]
     /// Directory listing format feature.
     pub dir_listing_format: DirListFmt,
     /// CORS feature.
@@ -65,6 +68,7 @@ pub struct RequestHandlerOpts {
     pub page_fallback: Vec<u8>,
     /// Basic auth feature.
     #[cfg(feature = "basic-auth")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "basic-auth")))]
     pub basic_auth: String,
     /// Log remote address feature.
     pub log_remote_address: bool,

diff --git a/src/lib.rs b/src/lib.rs
@@ -138,13 +138,15 @@ pub mod server;
 pub mod service;
 pub mod settings;
 #[cfg(any(unix, windows))]
+#[cfg_attr(docsrs, doc(cfg(any(unix, windows))))]
 pub mod signals;
 pub mod static_files;
 #[cfg(feature = "http2")]
 #[cfg_attr(docsrs, doc(cfg(feature = "http2")))]
 pub mod tls;
 pub mod transport;
 #[cfg(windows)]
+#[cfg_attr(docsrs, doc(cfg(windows)))]
 pub mod winservice;
 #[macro_use]
 pub mod error;

diff --git a/src/settings/file.rs b/src/settings/file.rs
@@ -135,25 +135,32 @@ pub struct General {
 
     /// HTTP/2 + TLS.
     #[cfg(feature = "http2")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "http2")))]
     pub http2: Option<bool>,
     /// Http2 tls certificate feature.
     #[cfg(feature = "http2")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "http2")))]
     pub http2_tls_cert: Option<PathBuf>,
     /// Http2 tls key feature.
     #[cfg(feature = "http2")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "http2")))]
     pub http2_tls_key: Option<PathBuf>,
 
     /// Redirect all HTTP requests to HTTPS.
     #[cfg(feature = "http2")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "http2")))]
     pub https_redirect: Option<bool>,
     /// HTTP host port where the redirect server will listen for requests to redirect them to HTTPS.
     #[cfg(feature = "http2")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "http2")))]
     pub https_redirect_host: Option<String>,
     /// Host port for redirecting HTTP requests to HTTPS.
     #[cfg(feature = "http2")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "http2")))]
     pub https_redirect_from_port: Option<u16>,
     /// List of host names or IPs allowed to redirect from.
     #[cfg(feature = "http2")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "http2")))]
     pub https_redirect_from_hosts: Option<String>,
 
     /// Security headers.
@@ -168,15 +175,20 @@ pub struct General {
 
     /// Directory listing feature.
     #[cfg(feature = "directory-listing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "directory-listing")))]
     pub directory_listing: Option<bool>,
     /// Directory listing order feature.
     #[cfg(feature = "directory-listing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "directory-listing")))]
     pub directory_listing_order: Option<u8>,
     /// Directory listing format feature.
     #[cfg(feature = "directory-listing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "directory-listing")))]
     pub directory_listing_format: Option<DirListFmt>,
 
     /// Basich Authentication feature.
+    #[cfg(feature = "basic-auth")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "basic-auth")))]
     pub basic_auth: Option<String>,
 
     /// File descriptor binding feature.

diff --git a/src/signals.rs b/src/signals.rs
@@ -18,6 +18,7 @@ use {
 use {std::sync::Arc, tokio::sync::watch::Receiver, tokio::sync::Mutex};
 
 #[cfg(unix)]
+#[cfg_attr(docsrs, doc(cfg(unix)))]
 /// It creates a common list of signals stream for `SIGTERM`, `SIGINT` and `SIGQUIT` to be observed.
 pub fn create_signals() -> Result<Signals> {
     Ok(Signals::new([SIGHUP, SIGTERM, SIGINT, SIGQUIT])?)
@@ -58,6 +59,7 @@ async fn delay_graceful_shutdown(grace_period_secs: u8) {
 }
 
 #[cfg(windows)]
+#[cfg_attr(docsrs, doc(cfg(windows)))]
 /// It waits for an incoming `ctrl+c` signal on Windows.
 pub async fn wait_for_ctrl_c(cancel_recv: Arc<Mutex<Option<Receiver<()>>>>, grace_period_secs: u8) {
     if let Some(receiver) = &mut *cancel_recv.lock().await {

diff --git a/src/static_files.rs b/src/static_files.rs
@@ -50,12 +50,15 @@ pub struct HandleOpts<'a> {
     pub uri_query: Option<&'a str>,
     /// Directory listing feature.
     #[cfg(feature = "directory-listing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "directory-listing")))]
     pub dir_listing: bool,
     /// Directory listing order feature.
     #[cfg(feature = "directory-listing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "directory-listing")))]
     pub dir_listing_order: u8,
     /// Directory listing format feature.
     #[cfg(feature = "directory-listing")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "directory-listing")))]
     pub dir_listing_format: &'a DirListFmt,
     /// Redirect trailing slash feature.
     pub redirect_trailing_slash: bool,