Added doc_cfg where appropriate and silenced warnings when building t…

…he docs (#57)
veeso · Oct 9, 2023 · 9b45545 · 9b45545
1 parent 0da2348
commit 9b45545
Show file tree

Hide file tree

Showing 8 changed files with 43 additions and 0 deletions.
diff --git a/suppaftp/Cargo.toml b/suppaftp/Cargo.toml
@@ -76,3 +76,7 @@ no-log = ["log/max_level_off"]
 
 # Must be enabled whenever testing with docker containers
 with-containers = []
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
diff --git a/suppaftp/src/async_ftp/mod.rs b/suppaftp/src/async_ftp/mod.rs
@@ -118,6 +118,7 @@ where
     /// let mut ftp_stream = ftp_stream.into_secure(ctx, "localhost").await.unwrap();
     /// ```
     #[cfg(feature = "async-secure")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "async-secure")))]
     pub async fn into_secure(
         mut self,
         tls_connector: impl AsyncTlsConnector<Stream = T> + 'static,
@@ -172,6 +173,10 @@ where
     /// let mut ftp_stream = ImplAsyncFtpStream::connect_secure_implicit("127.0.0.1:990", ctx, "localhost").await.unwrap();
     /// ```
     #[cfg(all(feature = "async-secure", feature = "deprecated"))]
+    #[cfg_attr(
+        docsrs,
+        doc(cfg(all(feature = "async-secure", feature = "deprecated")))
+    )]
     pub async fn connect_secure_implicit<A: ToSocketAddrs>(
         addr: A,
         tls_connector: impl AsyncTlsConnector<Stream = T> + 'static,
@@ -269,6 +274,7 @@ where
     /// Once the command is performed, the command channel will be encrypted no more.
     /// The data stream will still be secure.
     #[cfg(feature = "async-secure")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "async-secure")))]
     pub async fn clear_command_channel(mut self) -> FtpResult<Self> {
         // Ask the server to stop securing data
         debug!("performing clear command channel");

diff --git a/suppaftp/src/command.rs b/suppaftp/src/command.rs
@@ -16,9 +16,11 @@ pub enum Command {
     Appe(String),
     /// Set auth to TLS
     #[cfg(any(feature = "secure", feature = "async-secure"))]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "secure", feature = "async-secure"))))]
     Auth,
     /// Ask server not to encrypt command channel
     #[cfg(any(feature = "secure", feature = "async-secure"))]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "secure", feature = "async-secure"))))]
     ClearCommandChannel,
     /// Change directory to parent directory
     Cdup,
@@ -50,11 +52,13 @@ pub enum Command {
     Pasv,
     /// Protection buffer size
     #[cfg(any(feature = "secure", feature = "async-secure"))]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "secure", feature = "async-secure"))))]
     Pbsz(usize),
     /// Specifies an address and port to which the server should connect (active mode)
     Port(String),
     /// Set protection level for protocol
     #[cfg(any(feature = "secure", feature = "async-secure"))]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "secure", feature = "async-secure"))))]
     Prot(ProtectionLevel),
     /// Print working directory
     Pwd,
@@ -81,6 +85,7 @@ pub enum Command {
 }
 
 #[cfg(any(feature = "secure", feature = "async-secure"))]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "secure", feature = "async-secure"))))]
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[allow(unused)]
 /// Protection level; argument for `Prot` command

diff --git a/suppaftp/src/lib.rs b/suppaftp/src/lib.rs
@@ -1,5 +1,6 @@
 #![crate_name = "suppaftp"]
 #![crate_type = "lib"]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 //! # SuppaFTP
 //!
@@ -144,11 +145,14 @@ pub mod types;
 
 // -- secure deps
 #[cfg(feature = "native-tls")]
+// #[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))]
 pub extern crate native_tls_crate as native_tls;
 #[cfg(feature = "rustls")]
+// #[cfg_attr(docsrs, doc(cfg(feature = "rustls")))]
 pub extern crate rustls_crate as rustls;
 // -- async deps
 #[cfg(feature = "async-native-tls")]
+// #[cfg_attr(docsrs, doc(cfg(feature = "async-native-tls")))]
 pub extern crate async_native_tls_crate as async_native_tls;
 
 // -- export (common)
@@ -161,41 +165,57 @@ pub type FtpStream = ImplFtpStream<NoTlsStream>;
 pub use sync_ftp::DataStream;
 // -- export secure (native-tls)
 #[cfg(feature = "native-tls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))]
 pub use sync_ftp::NativeTlsConnector;
 #[cfg(feature = "native-tls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))]
 use sync_ftp::NativeTlsStream;
 #[cfg(feature = "native-tls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "native-tls")))]
 pub type NativeTlsFtpStream = ImplFtpStream<NativeTlsStream>;
 // -- export secure (rustls)
 #[cfg(feature = "rustls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "rustls")))]
 pub use sync_ftp::RustlsConnector;
 #[cfg(feature = "rustls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "rustls")))]
 use sync_ftp::RustlsStream;
 #[cfg(feature = "rustls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "rustls")))]
 pub type RustlsFtpStream = ImplFtpStream<RustlsStream>;
 
 // -- export async
 #[cfg(feature = "async")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
 use async_ftp::AsyncNoTlsStream;
 #[cfg(feature = "async")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
 pub use async_ftp::ImplAsyncFtpStream;
 #[cfg(feature = "async")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
 pub type AsyncFtpStream = ImplAsyncFtpStream<AsyncNoTlsStream>;
 // -- export async secure (native-tls)
 #[cfg(feature = "async-native-tls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async-native-tls")))]
 pub use async_ftp::AsyncNativeTlsConnector;
 #[cfg(feature = "async-native-tls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async-native-tls")))]
 use async_ftp::AsyncNativeTlsStream;
 #[cfg(feature = "async")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
 pub use async_ftp::DataStream as AsyncDataStream;
 #[cfg(feature = "async-native-tls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async-native-tls")))]
 pub type AsyncNativeTlsFtpStream = ImplAsyncFtpStream<AsyncNativeTlsStream>;
 // -- export async secure (rustls)
 #[cfg(feature = "async-rustls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async-rustls")))]
 pub use async_ftp::AsyncRustlsConnector;
 #[cfg(feature = "async-rustls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async-rustls")))]
 use async_ftp::AsyncRustlsStream;
 #[cfg(feature = "async-rustls")]
+#[cfg_attr(docsrs, doc(cfg(feature = "async-rustls")))]
 pub type AsyncRustlsFtpStream = ImplAsyncFtpStream<AsyncRustlsStream>;
 
 // -- test logging

diff --git a/suppaftp/src/list.rs b/suppaftp/src/list.rs
@@ -288,9 +288,12 @@ impl File {
     /// Try to parse a "LIST" output command line in DOS format.
     /// Returns error if syntax is not DOS compliant.
     /// DOS syntax has the following syntax:
+    ///
+    /// ```text
     /// {DATE} {TIME} {<DIR> | SIZE} {FILENAME}
     /// 10-19-20  03:19PM <DIR> pub
     /// 04-08-14  03:09PM 403   readme.txt
+    /// ```
     pub fn from_dos_line(line: &str) -> Result<Self, ParseError> {
         // Apply regex to result
         match DOS_LS_RE.captures(line) {

diff --git a/suppaftp/src/sync_ftp/data_stream.rs b/suppaftp/src/sync_ftp/data_stream.rs
@@ -18,6 +18,7 @@ where
 }
 
 #[cfg(feature = "secure")]
+#[cfg_attr(docsrs, doc(cfg(feature = "secure")))]
 impl<T> DataStream<T>
 where
     T: TlsStream,

diff --git a/suppaftp/src/sync_ftp/mod.rs b/suppaftp/src/sync_ftp/mod.rs
@@ -131,6 +131,7 @@ where
     /// let mut ftp_stream = ftp_stream.into_secure(ctx, "localhost").unwrap();
     /// ```
     #[cfg(feature = "secure")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "secure")))]
     pub fn into_secure(
         mut self,
         tls_connector: impl TlsConnector<Stream = T> + 'static,
@@ -180,6 +181,7 @@ where
     /// let mut ftp_stream = FtpStream::connect_secure_implicit("127.0.0.1:990", ctx, "localhost").unwrap();
     /// ```
     #[cfg(all(feature = "secure", feature = "deprecated"))]
+    #[cfg_attr(docsrs, doc(cfg(all(feature = "secure", feature = "deprecated"))))]
     pub fn connect_secure_implicit<A: ToSocketAddrs>(
         addr: A,
         tls_connector: impl TlsConnector<Stream = T> + 'static,
@@ -268,6 +270,7 @@ where
     /// Once the command is performed, the command channel will be encrypted no more.
     /// The data stream will still be secure.
     #[cfg(feature = "secure")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "secure")))]
     pub fn clear_command_channel(mut self) -> FtpResult<Self> {
         // Ask the server to stop securing data
         debug!("performing clear command channel");

diff --git a/suppaftp/src/types.rs b/suppaftp/src/types.rs
@@ -23,6 +23,7 @@ pub enum FtpError {
     ConnectionError(std::io::Error),
     /// There was an error with the secure stream
     #[cfg(any(feature = "secure", feature = "async-secure"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "async-secure")))]
     #[error("Secure error: {0}")]
     SecureError(String),
     /// Unexpected response from remote. The command expected a certain response, but got another one.