secrecy: add doc_cfg (#464)

Improves `rustdoc` documentation by notating types which are
conditionally available based on cargo features.

secrecy/Cargo.toml

@@ -16,9 +16,6 @@ readme      = "README.md"
 categories  = ["cryptography", "memory-management", "no-std", "os"]
 keywords    = ["clear", "memory", "secret", "secure", "wipe"]
 
-[badges]
-maintenance = { status = "passively-maintained" }
-
 [dependencies]
 serde = { version = "1", optional = true }
 zeroize = { version = "1.1", path = "../zeroize", default-features = false }
@@ -30,3 +27,4 @@ alloc = ["zeroize/alloc"]
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

secrecy/src/boxed.rs

@@ -5,8 +5,7 @@ use alloc::boxed::Box;
 use zeroize::Zeroize;
 
 /// `Box` types containing a secret value
-#[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 pub type SecretBox<S> = Secret<Box<S>>;
 
-#[cfg(feature = "alloc")]
 impl<S: DebugSecret + Zeroize> DebugSecret for Box<S> {}

secrecy/src/bytes.rs

@@ -8,12 +8,13 @@ use zeroize::Zeroize;
 #[cfg(all(feature = "bytes", feature = "serde"))]
 use serde::de::{self, Deserialize};
 
-/// Instance of `BytesMut` protected by a type that impls the `ExposeSecret`
+/// Instance of [`BytesMut`] protected by a type that impls the [`ExposeSecret`]
 /// trait like `Secret<T>`.
 ///
-/// Because of the nature of how the `Bytes` type works, it needs some special
+/// Because of the nature of how the `BytesMut` type works, it needs some special
 /// care in order to have a proper zeroizing drop handler.
 #[derive(Clone)]
+#[cfg_attr(docsrs, doc(cfg(feature = "bytes")))]
 pub struct SecretBytesMut(BytesMut);
 
 impl SecretBytesMut {

secrecy/src/lib.rs

@@ -2,9 +2,10 @@
 //! (e.g. passwords, cryptographic keys, access tokens or other credentials)
 
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![doc(html_root_url = "https://docs.rs/secrecy/0.6.0")]
 #![forbid(unsafe_code)]
 #![warn(missing_docs, rust_2018_idioms, unused_qualifications)]
-#![doc(html_root_url = "https://docs.rs/secrecy/0.6.0")]
 
 #[cfg(feature = "alloc")]
 extern crate alloc;
@@ -161,12 +162,12 @@ impl_debug_secret_for_array!(
 /// by design these types do *NOT* impl this trait.
 ///
 /// If you really want to have `serde` serialize those types, use the
-/// `serialize_with` attribute to specify a serializer that exposes the secret:
-///
-/// <https://serde.rs/field-attrs.html#serialize_with>
+/// [`serialize_with`][2] attribute to specify a serializer that exposes the secret.
 ///
 /// [1]: https://docs.rs/secrecy/latest/secrecy/struct.Secret.html#implementations
+/// [2]: https://serde.rs/field-attrs.html#serialize_with
 #[cfg(feature = "serde")]
+#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
 pub trait SerializableSecret: Serialize {}
 
 #[cfg(feature = "serde")]

secrecy/src/string.rs

@@ -5,13 +5,15 @@ use alloc::str::FromStr;
 use alloc::string::{String, ToString};
 
 /// Secret strings
+#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 pub type SecretString = Secret<String>;
 
 impl DebugSecret for String {}
 impl CloneableSecret for String {}
 
 impl FromStr for SecretString {
     type Err = core::convert::Infallible;
+
     fn from_str(src: &str) -> Result<Self, Self::Err> {
         Ok(SecretString::new(src.to_string()))
     }

secrecy/src/vec.rs

@@ -1,12 +1,12 @@
 //! Secret `Vec` types
 
-use super::{DebugSecret, Secret};
+use super::{CloneableSecret, DebugSecret, Secret};
 use alloc::vec::Vec;
 use zeroize::Zeroize;
 
 /// `Vec` types containing secret value
-#[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 pub type SecretVec<S> = Secret<Vec<S>>;
 
-#[cfg(feature = "alloc")]
+impl<S: CloneableSecret + Zeroize> CloneableSecret for Vec<S> {}
 impl<S: DebugSecret + Zeroize> DebugSecret for Vec<S> {}