Migrate to doc_auto_cfg (#1370)

Migrates the `aead`, `cipher`, `crypto-common`, `digest`, and `universal-hash` crates to use the `doc_auto_cfg` feature which automatically generates documentation for `cfg`-gated code, which in our uses is almost exclusively gated on crate features. This allows the previous manual `doc_cfg` annotations to be removed, which is nice as they otherwise duplicate work whenever `cfg`-gated code is used.
RustCrypto · Oct 31, 2023 · bbcb9c2 · bbcb9c2
1 parent 2a1016f
commit bbcb9c2
Show file tree

Hide file tree

Showing 20 changed files with 6 additions and 88 deletions.
diff --git a/aead/src/dev.rs b/aead/src/dev.rs
@@ -3,7 +3,6 @@ pub use blobby;
 
 /// Define AEAD test
 #[macro_export]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! new_test {
     ($name:ident, $test_name:expr, $cipher:ty $(,)?) => {
         #[test]

diff --git a/aead/src/lib.rs b/aead/src/lib.rs
@@ -14,7 +14,7 @@
 //! [RustCrypto/AEADs]: https://github.com/RustCrypto/AEADs
 
 #![no_std]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
     html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
@@ -29,34 +29,27 @@ extern crate alloc;
 extern crate std;
 
 #[cfg(feature = "dev")]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 pub mod dev;
 
 #[cfg(feature = "stream")]
-#[cfg_attr(docsrs, doc(cfg(feature = "stream")))]
 pub mod stream;
 
 pub use crypto_common::{Key, KeyInit, KeySizeUser};
 pub use generic_array::{self, typenum::consts};
 
 #[cfg(feature = "arrayvec")]
-#[cfg_attr(docsrs, doc(cfg(feature = "arrayvec")))]
 pub use arrayvec;
 
 #[cfg(feature = "bytes")]
-#[cfg_attr(docsrs, doc(cfg(feature = "bytes")))]
 pub use bytes;
 
 #[cfg(feature = "getrandom")]
-#[cfg_attr(docsrs, doc(cfg(feature = "getrandom")))]
 pub use crypto_common::rand_core::OsRng;
 
 #[cfg(feature = "heapless")]
-#[cfg_attr(docsrs, doc(cfg(feature = "heapless")))]
 pub use heapless;
 
 #[cfg(feature = "rand_core")]
-#[cfg_attr(docsrs, doc(cfg(feature = "rand_core")))]
 pub use crypto_common::rand_core;
 
 use core::fmt;
@@ -147,7 +140,6 @@ pub trait AeadCore {
     ///
     /// [NIST SP 800-38D]: https://csrc.nist.gov/publications/detail/sp/800-38d/final
     #[cfg(feature = "rand_core")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "rand_core")))]
     fn generate_nonce(mut rng: impl CryptoRng + RngCore) -> Nonce<Self>
     where
         Nonce<Self>: Default,
@@ -163,7 +155,6 @@ pub trait AeadCore {
 /// This trait is intended for use with stateless AEAD algorithms. The
 /// [`AeadMut`] trait provides a stateful interface.
 #[cfg(feature = "alloc")]
-#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 pub trait Aead: AeadCore {
     /// Encrypt the given plaintext payload, and return the resulting
     /// ciphertext as a vector of bytes.
@@ -220,7 +211,6 @@ pub trait Aead: AeadCore {
 
 /// Stateful Authenticated Encryption with Associated Data algorithm.
 #[cfg(feature = "alloc")]
-#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 pub trait AeadMut: AeadCore {
     /// Encrypt the given plaintext slice, and return the resulting ciphertext
     /// as a vector of bytes.
@@ -480,7 +470,6 @@ impl<Alg: AeadInPlace> AeadMutInPlace for Alg {
 /// If you don't care about AAD, you can pass a `&[u8]` as the payload to
 /// `encrypt`/`decrypt` and it will automatically be coerced to this type.
 #[cfg(feature = "alloc")]
-#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 pub struct Payload<'msg, 'aad> {
     /// Message to be encrypted/decrypted
     pub msg: &'msg [u8],

diff --git a/aead/src/stream.rs b/aead/src/stream.rs
@@ -131,7 +131,6 @@ where
     /// Encrypt the given plaintext payload, and return the resulting
     /// ciphertext as a vector of bytes.
     #[cfg(feature = "alloc")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
     fn encrypt<'msg, 'aad>(
         &self,
         position: Self::Counter,
@@ -148,7 +147,6 @@ where
     /// Decrypt the given ciphertext slice, and return the resulting plaintext
     /// as a vector of bytes.
     #[cfg(feature = "alloc")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
     fn decrypt<'msg, 'aad>(
         &self,
         position: Self::Counter,
@@ -259,7 +257,6 @@ macro_rules! impl_stream_object {
             #[doc = "the next AEAD message in this STREAM, returning the"]
             #[doc = "result as a [`Vec`]."]
             #[cfg(feature = "alloc")]
-            #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
             pub fn $next_method<'msg, 'aad>(
                 &mut self,
                 payload: impl Into<Payload<'msg, 'aad>>,
@@ -308,7 +305,6 @@ macro_rules! impl_stream_object {
             #[doc = $obj_desc]
             #[doc = "object in order to prevent further use."]
             #[cfg(feature = "alloc")]
-            #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
             pub fn $last_method<'msg, 'aad>(
                 self,
                 payload: impl Into<Payload<'msg, 'aad>>,

diff --git a/cipher/src/block.rs b/cipher/src/block.rs
@@ -133,7 +133,6 @@ pub trait BlockEncrypt: BlockSizeUser + Sized {
     ///
     /// Returns [`PadError`] if length of output buffer is not sufficient.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn encrypt_padded_inout<'out, P: Padding<Self::BlockSize>>(
         &self,
@@ -151,7 +150,6 @@ pub trait BlockEncrypt: BlockSizeUser + Sized {
     ///
     /// Returns [`PadError`] if length of output buffer is not sufficient.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn encrypt_padded<'a, P: Padding<Self::BlockSize>>(
         &self,
@@ -166,7 +164,6 @@ pub trait BlockEncrypt: BlockSizeUser + Sized {
     ///
     /// Returns [`PadError`] if length of output buffer is not sufficient.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn encrypt_padded_b2b<'a, P: Padding<Self::BlockSize>>(
         &self,
@@ -179,7 +176,6 @@ pub trait BlockEncrypt: BlockSizeUser + Sized {
 
     /// Pad input and encrypt into a newly allocated Vec. Returns resulting ciphertext Vec.
     #[cfg(all(feature = "block-padding", feature = "alloc"))]
-    #[cfg_attr(docsrs, doc(cfg(all(feature = "block-padding", feature = "alloc"))))]
     #[inline]
     fn encrypt_padded_vec<P: Padding<Self::BlockSize>>(&self, msg: &[u8]) -> Vec<u8> {
         let mut out = allocate_out_vec::<Self>(msg.len());
@@ -249,7 +245,6 @@ pub trait BlockDecrypt: BlockSizeUser {
     /// Returns [`UnpadError`] if padding is malformed or if input length is
     /// not multiple of `Self::BlockSize`.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn decrypt_padded_inout<'out, P: Padding<Self::BlockSize>>(
         &self,
@@ -268,7 +263,6 @@ pub trait BlockDecrypt: BlockSizeUser {
     /// Returns [`UnpadError`] if padding is malformed or if input length is
     /// not multiple of `Self::BlockSize`.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn decrypt_padded<'a, P: Padding<Self::BlockSize>>(
         &self,
@@ -283,7 +277,6 @@ pub trait BlockDecrypt: BlockSizeUser {
     /// Returns [`UnpadError`] if padding is malformed or if input length is
     /// not multiple of `Self::BlockSize`.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn decrypt_padded_b2b<'a, P: Padding<Self::BlockSize>>(
         &self,
@@ -305,7 +298,6 @@ pub trait BlockDecrypt: BlockSizeUser {
     /// Returns [`UnpadError`] if padding is malformed or if input length is
     /// not multiple of `Self::BlockSize`.
     #[cfg(all(feature = "block-padding", feature = "alloc"))]
-    #[cfg_attr(docsrs, doc(cfg(all(feature = "block-padding", feature = "alloc"))))]
     #[inline]
     fn decrypt_padded_vec<P: Padding<Self::BlockSize>>(
         &self,
@@ -378,7 +370,6 @@ pub trait BlockEncryptMut: BlockSizeUser + Sized {
     ///
     /// Returns [`PadError`] if length of output buffer is not sufficient.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn encrypt_padded_inout_mut<'out, P: Padding<Self::BlockSize>>(
         mut self,
@@ -396,7 +387,6 @@ pub trait BlockEncryptMut: BlockSizeUser + Sized {
     ///
     /// Returns [`PadError`] if length of output buffer is not sufficient.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn encrypt_padded_mut<P: Padding<Self::BlockSize>>(
         self,
@@ -411,7 +401,6 @@ pub trait BlockEncryptMut: BlockSizeUser + Sized {
     ///
     /// Returns [`PadError`] if length of output buffer is not sufficient.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn encrypt_padded_b2b_mut<'a, P: Padding<Self::BlockSize>>(
         self,
@@ -424,7 +413,6 @@ pub trait BlockEncryptMut: BlockSizeUser + Sized {
 
     /// Pad input and encrypt into a newly allocated Vec. Returns resulting ciphertext Vec.
     #[cfg(all(feature = "block-padding", feature = "alloc"))]
-    #[cfg_attr(docsrs, doc(cfg(all(feature = "block-padding", feature = "alloc"))))]
     #[inline]
     fn encrypt_padded_vec_mut<P: Padding<Self::BlockSize>>(self, msg: &[u8]) -> Vec<u8> {
         let mut out = allocate_out_vec::<Self>(msg.len());
@@ -498,7 +486,6 @@ pub trait BlockDecryptMut: BlockSizeUser + Sized {
     /// Returns [`UnpadError`] if padding is malformed or if input length is
     /// not multiple of `Self::BlockSize`.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn decrypt_padded_inout_mut<'out, P: Padding<Self::BlockSize>>(
         mut self,
@@ -517,7 +504,6 @@ pub trait BlockDecryptMut: BlockSizeUser + Sized {
     /// Returns [`UnpadError`] if padding is malformed or if input length is
     /// not multiple of `Self::BlockSize`.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn decrypt_padded_mut<P: Padding<Self::BlockSize>>(
         self,
@@ -532,7 +518,6 @@ pub trait BlockDecryptMut: BlockSizeUser + Sized {
     /// Returns [`UnpadError`] if padding is malformed or if input length is
     /// not multiple of `Self::BlockSize`.
     #[cfg(feature = "block-padding")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
     #[inline]
     fn decrypt_padded_b2b_mut<'a, P: Padding<Self::BlockSize>>(
         self,
@@ -554,7 +539,6 @@ pub trait BlockDecryptMut: BlockSizeUser + Sized {
     /// Returns [`UnpadError`] if padding is malformed or if input length is
     /// not multiple of `Self::BlockSize`.
     #[cfg(all(feature = "block-padding", feature = "alloc"))]
-    #[cfg_attr(docsrs, doc(cfg(all(feature = "block-padding", feature = "alloc"))))]
     #[inline]
     fn decrypt_padded_vec_mut<P: Padding<Self::BlockSize>>(
         self,

diff --git a/cipher/src/dev/block.rs b/cipher/src/dev/block.rs
@@ -4,7 +4,6 @@ pub use blobby;
 
 /// Define block cipher test
 #[macro_export]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! block_cipher_test {
     ($name:ident, $test_name:expr, $cipher:ty $(,)?) => {
         #[test]
@@ -99,7 +98,6 @@ macro_rules! block_cipher_test {
 
 /// Define block mode encryption test
 #[macro_export]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! block_mode_enc_test {
     ($name:ident, $test_name:expr, $cipher:ty $(,)?) => {
         #[test]
@@ -158,7 +156,6 @@ macro_rules! block_mode_enc_test {
 
 /// Define block mode decryption test
 #[macro_export]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! block_mode_dec_test {
     ($name:ident, $test_name:expr, $cipher:ty $(,)?) => {
         #[test]
@@ -217,7 +214,6 @@ macro_rules! block_mode_dec_test {
 
 /// Define `IvState` test
 #[macro_export]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! iv_state_test {
     ($name:ident, $cipher:ty, encrypt $(,)?) => {
         $crate::iv_state_test!($name, $cipher, encrypt_blocks_mut);
@@ -266,7 +262,6 @@ macro_rules! iv_state_test {
 
 /// Define block encryptor benchmark
 #[macro_export]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! block_encryptor_bench {
     (Key: $cipher:ty, $block_name:ident, $blocks_name:ident $(,)? ) => {
         $crate::block_encryptor_bench!(
@@ -328,7 +323,6 @@ macro_rules! block_encryptor_bench {
 
 /// Define block decryptor benchmark
 #[macro_export]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! block_decryptor_bench {
     (Key: $cipher:ty, $block_name:ident, $blocks_name:ident $(,)? ) => {
         $crate::block_decryptor_bench!(

diff --git a/cipher/src/dev/stream.rs b/cipher/src/dev/stream.rs
@@ -2,7 +2,6 @@
 
 /// Test core functionality of synchronous stream cipher
 #[macro_export]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! stream_cipher_test {
     ($name:ident, $test_name:expr, $cipher:ty $(,)?) => {
         #[test]
@@ -38,7 +37,6 @@ macro_rules! stream_cipher_test {
 
 /// Test stream synchronous stream cipher seeking capabilities
 #[macro_export]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! stream_cipher_seek_test {
     ($name:ident, $cipher:ty) => {
         #[test]
@@ -91,7 +89,6 @@ macro_rules! stream_cipher_seek_test {
 
 /// Create stream cipher benchmarks
 #[macro_export]
-#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! stream_cipher_bench {
     (
         $cipher:ty;

diff --git a/cipher/src/errors.rs b/cipher/src/errors.rs
@@ -18,7 +18,6 @@ impl fmt::Display for StreamCipherError {
 }
 
 #[cfg(feature = "std")]
-#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 impl std::error::Error for StreamCipherError {}
 
 /// The error type returned when a cipher position can not be represented
@@ -39,5 +38,4 @@ impl From<OverflowError> for StreamCipherError {
 }
 
 #[cfg(feature = "std")]
-#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 impl std::error::Error for OverflowError {}
diff --git a/cipher/src/lib.rs b/cipher/src/lib.rs
@@ -6,7 +6,7 @@
 //! [3]: https://en.wikipedia.org/wiki/Stream_cipher
 
 #![no_std]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
     html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
@@ -23,15 +23,12 @@ extern crate alloc;
 extern crate std;
 
 #[cfg(feature = "rand_core")]
-#[cfg_attr(docsrs, doc(cfg(feature = "rand_core")))]
 pub use crypto_common::rand_core;
 
 #[cfg(feature = "block-padding")]
-#[cfg_attr(docsrs, doc(cfg(feature = "block-padding")))]
 pub use inout::block_padding;
 
 #[cfg(feature = "zeroize")]
-#[cfg_attr(docsrs, doc(cfg(feature = "zeroize")))]
 pub use zeroize;
 
 #[cfg(feature = "dev")]