digest: document three levels of organization

digest/src/fixed.rs

@@ -49,7 +49,9 @@ pub trait FixedOutputDirty {
 
     /// Retrieve result into provided buffer and leave hasher in a dirty state.
     ///
-    /// Implementations should panic if this is called twice without resetting.
+    /// This method is expected to only be called once unless
+    /// [`Reset::reset`] is called, after which point it can be
+    /// called again and reset again (and so on).
     fn finalize_into_dirty(&mut self, out: &mut GenericArray<u8, Self::OutputSize>);
 }
 

digest/src/lib.rs

@@ -1,15 +1,24 @@
 //! This crate provides traits which describe functionality of cryptographic hash
 //! functions.
 //!
-//! Traits in this repository can be separated into two levels:
-//! - Low level traits: [`Update`], [`BlockInput`], [`Reset`], [`FixedOutput`],
-//! [`VariableOutput`], [`ExtendableOutput`]. These traits atomically describe
-//! available functionality of hash function implementations.
-//! - Convenience trait: [`Digest`], [`DynDigest`]. They are wrappers around
-//! low level traits for most common hash-function use-cases.
+//! Traits in this repository are organized into high-level convenience traits,
+//! mid-level traits which expose more fine-grained functionality, and
+//! low-level traits intended to only be used by algorithm implementations:
 //!
-//! Additionally hash functions implement traits from `std`: `Default`, `Clone`,
-//! `Write`. (the latter depends on enabled-by-default `std` crate feature)
+//! - **High-level convenience traits**: [`Digest`], [`DynDigest`]. They are wrappers
+//!   around lower-level traits for most common hash-function use-cases.
+//! - **Mid-level traits**: [`Update`], [`BlockInput`], [`Reset`], [`FixedOutput`],
+//!   [`VariableOutput`], [`ExtendableOutput`]. These traits atomically describe
+//!   available functionality of hash function implementations.
+//! - **Low-level traits**: [`FixedOutputDirty`], [`VariableOutputDirty`],
+//!   [`ExtendableOutputDirty`]. These traits are intended to be implemented by
+//!   low-level algorithm providers only and simplify the amount of work
+//!   implementers need to do and therefore shouldn't be used in
+//!   application-level code.
+//!
+//! Additionally hash functions implement traits from the standard library:
+//! `Default`, `Clone`, `Write`. The latter is feature-gated behind `std` feature,
+//! which is usually enabled by default by hash implementation crates.
 //!
 //! The [`Digest`] trait is the most commonly used trait.
 

digest/src/variable.rs

@@ -78,7 +78,9 @@ pub trait VariableOutputDirty: Sized {
 
     /// Retrieve result into provided buffer and leave hasher in a dirty state.
     ///
-    /// Implementations should panic if this is called twice without resetting.
+    /// This method is expected to only be called once unless
+    /// [`Reset::reset`] is called, after which point it can be
+    /// called again and reset again (and so on).
     fn finalize_variable_dirty(&mut self, f: impl FnOnce(&[u8]));
 }
 

digest/src/xof.rs

@@ -77,9 +77,11 @@ pub trait ExtendableOutputDirty: Sized {
     /// Reader
     type Reader: XofReader;
 
-    /// Retrieve XOF reader and consume hasher instance.
+    /// Retrieve XOF reader.
     ///
-    /// Implementations should panic if this is called twice without resetting.
+    /// This method is expected to only be called once unless
+    /// [`Reset::reset`] is called, after which point it can be
+    /// called again and reset again (and so on).
     fn finalize_xof_dirty(&mut self) -> Self::Reader;
 }