Merge pull request RustCrypto#166 from RustCrypto/doc-improvements

block-cipher/crypto-mac: add doc_cfg + comments
dns2utf8 · Jun 3, 2020 · 2b87aba · 2b87aba
2 parents c226638 + cebfee5
commit 2b87aba
Show file tree

Hide file tree

Showing 6 changed files with 22 additions and 3 deletions.
diff --git a/block-cipher/Cargo.toml b/block-cipher/Cargo.toml
@@ -20,4 +20,5 @@ std = []
 dev = ["blobby"]
 
 [package.metadata.docs.rs]
-features = [ "std" ]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
diff --git a/block-cipher/src/dev.rs b/block-cipher/src/dev.rs
@@ -4,6 +4,7 @@ pub use blobby;
 
 /// Define test
 #[macro_export]
+#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! new_test {
     ($name:ident, $test_name:expr, $cipher:ty) => {
         #[test]
@@ -109,6 +110,7 @@ macro_rules! new_test {
 
 /// Define benchmark
 #[macro_export]
+#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! bench {
     ($cipher:path, $key_len:expr) => {
         extern crate test;

diff --git a/block-cipher/src/lib.rs b/block-cipher/src/lib.rs
@@ -1,7 +1,17 @@
 //! This crate defines a set of simple traits used to define functionality of
-//! block ciphers.
+//! [block ciphers][1].
+//!
+//! # About block ciphers
+//!
+//! Block ciphers are keyed, deterministic permutations of a fixed-sized input
+//! "block" providing a reversible transformation to/from an encrypted output.
+//! They are one of the fundamental structural components of [symmetric cryptography][2].
+//!
+//! [1]: https://en.wikipedia.org/wiki/Block_cipher
+//! [2]: https://en.wikipedia.org/wiki/Symmetric-key_algorithm
 
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]
 #![forbid(unsafe_code)]
 #![warn(missing_docs, rust_2018_idioms)]
@@ -10,6 +20,7 @@
 extern crate std;
 
 #[cfg(feature = "dev")]
+#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 pub mod dev;
 
 mod errors;

diff --git a/crypto-mac/Cargo.toml b/crypto-mac/Cargo.toml
@@ -21,4 +21,5 @@ dev = ["blobby"]
 std = []
 
 [package.metadata.docs.rs]
-features = [ "std" ]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
diff --git a/crypto-mac/src/dev.rs b/crypto-mac/src/dev.rs
@@ -4,6 +4,7 @@ pub use blobby;
 
 /// Define test
 #[macro_export]
+#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! new_test {
     ($name:ident, $test_name:expr, $mac:ty) => {
         #[test]
@@ -58,6 +59,7 @@ macro_rules! new_test {
 
 /// Define benchmark
 #[macro_export]
+#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 macro_rules! bench {
     ($name:ident, $engine:path, $bs:expr) => {
         #[bench]

diff --git a/crypto-mac/src/lib.rs b/crypto-mac/src/lib.rs
@@ -1,6 +1,7 @@
 //! This crate provides trait for Message Authentication Code (MAC) algorithms.
 
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]
 #![forbid(unsafe_code)]
 #![warn(missing_docs, rust_2018_idioms)]
@@ -9,6 +10,7 @@
 extern crate std;
 
 #[cfg(feature = "dev")]
+#[cfg_attr(docsrs, doc(cfg(feature = "dev")))]
 pub mod dev;
 
 mod errors;