signature: enable/fix workspace-level lints; reformat docs (#2391)

tarcieri · web-flow · commit 5cb62a4def58 · 2026-04-23T08:56:20.000-06:00
Note: lint config was added in #2270
diff --git a/signature/Cargo.toml b/signature/Cargo.toml
@@ -20,5 +20,8 @@ rand_core = { version = "0.10", optional = true, default-features = false }
 alloc = []
 rand_core = ["dep:rand_core"]
 
+[lints]
+workspace = true
+
 [package.metadata.docs.rs]
 all-features = true
diff --git a/signature/src/error.rs b/signature/src/error.rs
@@ -30,6 +30,7 @@ pub struct Error {
 
 impl Error {
     /// Create a new error with no associated source
+    #[must_use]
     pub fn new() -> Self {
         Self::default()
     }
@@ -90,6 +91,7 @@ impl core::error::Error for Error {
             None
         }
         #[cfg(feature = "alloc")]
+        #[allow(trivial_casts)]
         {
             self.source
                 .as_ref()
diff --git a/signature/src/hazmat.rs b/signature/src/hazmat.rs
@@ -1,10 +1,14 @@
 //! Hazardous Materials: low-level APIs which can be insecure if misused.
 //!
-//! The traits in this module are not generally recommended, and should only be
-//! used in special cases where they are specifically needed.
+//! The traits in this module are not generally recommended, and should only be used in special
+//! cases where they are specifically needed.
 //!
-//! Using them incorrectly can introduce security vulnerabilities. Please
-//! carefully read the documentation before attempting to use them.
+//! <div class = "warning">
+//! <b>Security Warning</b>
+//!
+//! Using these traits incorrectly can introduce security vulnerabilities. Please carefully read the
+//! documentation before attempting to use them.
+//! </div>
 
 use crate::Error;
 
@@ -13,36 +17,38 @@ use crate::rand_core::TryCryptoRng;
 
 /// Sign the provided message prehash, returning a digital signature.
 pub trait PrehashSigner<S> {
-    /// Attempt to sign the given message digest, returning a digital signature
-    /// on success, or an error if something went wrong.
+    /// Attempt to sign the given message digest, returning a digital signature on success, or an
+    /// error if something went wrong.
+    ///
+    /// The `prehash` parameter should be the output of a secure cryptographic hash function.
     ///
-    /// The `prehash` parameter should be the output of a secure cryptographic
-    /// hash function.
+    /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths
+    /// for the message digest for a given concrete signature algorithm.
     ///
-    /// This API takes a `prehash` byte slice as there can potentially be many
-    /// compatible lengths for the message digest for a given concrete signature
-    /// algorithm.
+    /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide.
     ///
-    /// Allowed lengths are algorithm-dependent and up to a particular
-    /// implementation to decide.
+    /// # Errors
+    /// Returns [`Error`] in the event `prehash` is an invalid length.
     fn sign_prehash(&self, prehash: &[u8]) -> Result<S, Error>;
 }
 
-/// Sign the provided message prehash using the provided external randomness source, returning a digital signature.
+/// Sign the provided message prehash using the provided external randomness source, returning a
+/// digital signature.
 #[cfg(feature = "rand_core")]
 pub trait RandomizedPrehashSigner<S> {
-    /// Attempt to sign the given message digest, returning a digital signature
-    /// on success, or an error if something went wrong.
+    /// Attempt to sign the given message digest, returning a digital signature on success, or an
+    /// error if something went wrong.
     ///
-    /// The `prehash` parameter should be the output of a secure cryptographic
-    /// hash function.
+    /// The `prehash` parameter should be the output of a secure cryptographic hash function.
     ///
-    /// This API takes a `prehash` byte slice as there can potentially be many
-    /// compatible lengths for the message digest for a given concrete signature
-    /// algorithm.
+    /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths
+    /// for the message digest for a given concrete signature algorithm.
     ///
-    /// Allowed lengths are algorithm-dependent and up to a particular
-    /// implementation to decide.
+    /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide.
+    ///
+    /// # Errors
+    /// Returns [`Error`] in the event `prehash` is an invalid length, or if an internal error
+    /// in the provided `rng` occurs.
     fn sign_prehash_with_rng<R: TryCryptoRng + ?Sized>(
         &self,
         rng: &mut R,
@@ -52,57 +58,54 @@ pub trait RandomizedPrehashSigner<S> {
 
 /// Verify the provided message prehash using `Self` (e.g. a public key)
 pub trait PrehashVerifier<S> {
-    /// Use `Self` to verify that the provided signature for a given message
-    /// `prehash` is authentic.
+    /// Use `Self` to verify that the provided signature for a given message `prehash` is authentic.
+    ///
+    /// The `prehash` parameter MUST be the output of a secure cryptographic hash function.
     ///
-    /// The `prehash` parameter should be the output of a secure cryptographic
-    /// hash function.
+    /// <div class="warning">
+    /// <b>Security Warning</b>
     ///
-    /// Returns `Error` if it is inauthentic or some other error occurred, or
-    /// otherwise returns `Ok(())`.
+    /// If `prehash` is something other than the output of a cryptographically secure hash function,
+    /// an attacker can potentially forge signatures by e.g. solving a system of linear equations.
+    /// </div>
     ///
-    /// # ⚠️ Security Warning
+    /// Returns `Ok(())` if the signature verified successfully.
     ///
-    /// If `prehash` is something other than the output of a cryptographically
-    /// secure hash function, an attacker can potentially forge signatures by
-    /// solving a system of linear equations.
+    /// # Errors
+    /// Returns [`Error`] in the event the signature fails to verify or if `prehash` is an invalid
+    /// length.
     fn verify_prehash(&self, prehash: &[u8], signature: &S) -> Result<(), Error>;
 }
 
 /// Asynchronously sign the provided message prehash, returning a digital signature.
 #[allow(async_fn_in_trait)]
 pub trait AsyncPrehashSigner<S> {
-    /// Attempt to sign the given message digest, returning a digital signature
-    /// on success, or an error if something went wrong.
+    /// Attempt to sign the given message digest, returning a digital signature on success, or an
+    /// error if something went wrong.
     ///
-    /// The `prehash` parameter should be the output of a secure cryptographic
-    /// hash function.
+    /// The `prehash` parameter should be the output of a secure cryptographic hash function.
     ///
-    /// This API takes a `prehash` byte slice as there can potentially be many
-    /// compatible lengths for the message digest for a given concrete signature
-    /// algorithm.
+    /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths
+    /// for the message digest for a given concrete signature algorithm.
     ///
-    /// Allowed lengths are algorithm-dependent and up to a particular
-    /// implementation to decide.
+    /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide.
     async fn sign_prehash_async(&self, prehash: &[u8]) -> Result<S, Error>;
 }
 
-/// Asynchronously sign the provided message prehash using the provided external randomness source, returning a digital signature.
+/// Asynchronously sign the provided message prehash using the provided external randomness source,
+/// returning a digital signature.
 #[cfg(feature = "rand_core")]
 #[allow(async_fn_in_trait)]
 pub trait AsyncRandomizedPrehashSigner<S> {
-    /// Attempt to sign the given message digest, returning a digital signature
-    /// on success, or an error if something went wrong.
+    /// Attempt to sign the given message digest, returning a digital signature on success, or an
+    /// error if something went wrong.
     ///
-    /// The `prehash` parameter should be the output of a secure cryptographic
-    /// hash function.
+    /// The `prehash` parameter should be the output of a secure cryptographic hash function.
     ///
-    /// This API takes a `prehash` byte slice as there can potentially be many
-    /// compatible lengths for the message digest for a given concrete signature
-    /// algorithm.
+    /// This API takes a `prehash` byte slice as there can potentially be many compatible lengths
+    /// for the message digest for a given concrete signature algorithm.
     ///
-    /// Allowed lengths are algorithm-dependent and up to a particular
-    /// implementation to decide.
+    /// Allowed lengths are algorithm-dependent and up to a particular implementation to decide.
     async fn sign_prehash_with_rng_async<R: TryCryptoRng + ?Sized>(
         &self,
         rng: &mut R,
diff --git a/signature/src/lib.rs b/signature/src/lib.rs
@@ -7,15 +7,6 @@
 )]
 #![forbid(unsafe_code)]
 #![allow(async_fn_in_trait)]
-#![warn(
-    clippy::mod_module_files,
-    clippy::unwrap_used,
-    missing_docs,
-    rust_2018_idioms,
-    unused_lifetimes,
-    missing_debug_implementations,
-    unused_qualifications
-)]
 
 //! # Design
 //!
diff --git a/signature/src/signer.rs b/signature/src/signer.rs
diff --git a/signature/src/verifier.rs b/signature/src/verifier.rs

Original file line number	Diff line number	Diff line change
`@@ -30,6 +30,7 @@ pub struct Error {`
`30`	`30`
`31`	`31`	`impl Error {`
`32`	`32`	`/// Create a new error with no associated source`
	`33`	`+ #[must_use]`
`33`	`34`	`pub fn new() -> Self {`
`34`	`35`	`Self::default()`
`35`	`36`	`}`
`@@ -90,6 +91,7 @@ impl core::error::Error for Error {`
`90`	`91`	`None`
`91`	`92`	`}`
`92`	`93`	`#[cfg(feature = "alloc")]`
	`94`	`+ #[allow(trivial_casts)]`
`93`	`95`	`{`
`94`	`96`	`self.source`
`95`	`97`	`.as_ref()`