Merge pull request RustCrypto#79 from RustCrypto/signature/derive-docs

signature: improve docs for `signature_derive`
dns2utf8 · Mar 8, 2020 · 27a4ea6 · 27a4ea6
2 parents 4f28716 + 55ef493
commit 27a4ea6
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ Collection of traits which describe functionality of cryptographic primitives.
 | [`block-cipher-trait`](https://en.wikipedia.org/wiki/Block_cipher)| [![crates.io](https://img.shields.io/crates/v/block-cipher-trait.svg)](https://crates.io/crates/block-cipher-trait) | [![Documentation](https://docs.rs/block-cipher-trait/badge.svg)](https://docs.rs/block-cipher-trait) |
 | [`crypto-mac`](https://en.wikipedia.org/wiki/Message_authentication_code) | [![crates.io](https://img.shields.io/crates/v/crypto-mac.svg)](https://crates.io/crates/crypto-mac) | [![Documentation](https://docs.rs/crypto-mac/badge.svg)](https://docs.rs/crypto-mac) |
 | [`digest`](https://en.wikipedia.org/wiki/Cryptographic_hash_function) | [![crates.io](https://img.shields.io/crates/v/digest.svg)](https://crates.io/crates/digest) | [![Documentation](https://docs.rs/digest/badge.svg)](https://docs.rs/digest) |
-| [`signature`](https://en.wikipedia.org/wiki/Digital_signature) | [![crates.io](https://img.shields.io/crates/v/signature.svg)](https://crates.io/crates/stream-cipher) | [![Documentation](https://docs.rs/signature/badge.svg)](https://docs.rs/signature) |
+| [`signature`](https://en.wikipedia.org/wiki/Digital_signature) | [![crates.io](https://img.shields.io/crates/v/signature.svg)](https://crates.io/crates/signature) | [![Documentation](https://docs.rs/signature/badge.svg)](https://docs.rs/signature) |
 | [`stream-cipher`](https://en.wikipedia.org/wiki/Stream_cipher) | [![crates.io](https://img.shields.io/crates/v/stream-cipher.svg)](https://crates.io/crates/stream-cipher) | [![Documentation](https://docs.rs/stream-cipher/badge.svg)](https://docs.rs/stream-cipher) |
 
 ### Minimum Rust version

diff --git a/signature/signature_derive/src/lib.rs b/signature/signature_derive/src/lib.rs
@@ -29,7 +29,24 @@ fn derive_signer(mut s: synstructure::Structure) -> TokenStream {
         }
     })
 }
-decl_derive!([Signer] => derive_signer);
+
+decl_derive! {
+    [Signer] =>
+    /// Derive the [`Signer`] trait for a type which impls [`DigestSigner`].
+    ///
+    /// When implementing the [`DigestSigner`] trait for a signature type which
+    /// itself impl's the [`DigestSignature`] trait (which marks signature
+    /// algorithms which are computed using a [`Digest`]), signature providers
+    /// can automatically derive the [`Signer`] trait when the digest algorithm
+    /// is [`DigestSignature::Digest`] (i.e. the "standard" digest algorithm
+    /// for a given signature type)
+    ///
+    /// This automates all of the digest computation otherwise needed for a
+    /// complete signature algorithm implementation.
+    ///
+    /// [`Digest`]: https://docs.rs/digest/latest/digest/trait.Digest.html
+    derive_signer
+}
 
 /// Derive the `Verifier` trait for `DigestVerifier` types
 fn derive_verifier(mut s: synstructure::Structure) -> TokenStream {
@@ -46,7 +63,24 @@ fn derive_verifier(mut s: synstructure::Structure) -> TokenStream {
         }
     })
 }
-decl_derive!([Verifier] => derive_verifier);
+
+decl_derive! {
+    [Verifier] =>
+    /// Derive the [`Verifier`] trait for a type which impls [`DigestVerifier`].
+    ///
+    /// When implementing the [`DigestVerifier`] trait for a signature type which
+    /// itself impl's the [`DigestSignature`] trait (which marks signature
+    /// algorithms which are computed using a [`Digest`]), signature providers
+    /// can automatically derive the [`Verifier`] trait when the digest algorithm
+    /// is [`DigestSignature::Digest`] (i.e. the "standard" digest algorithm
+    /// for a given signature type)
+    ///
+    /// This automates all of the digest computation otherwise needed for a
+    /// complete signature algorithm implementation.
+    ///
+    /// [`Digest`]: https://docs.rs/digest/latest/digest/trait.Digest.html
+    derive_verifier
+}
 
 #[cfg(test)]
 mod tests {