digest: document three levels of organization

The new `*Dirty` traits add another level of organization to the crate's
design. This commit updates the documentation to reflect that.

digest/src/lib.rs

@@ -1,12 +1,20 @@
 //! 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:
+//!
+//! - **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, but may panic if used incorrectly and therefore
+//!   shouldn't be used in application-level code.
 //!
 //! Additionally hash functions implement traits from `std`: `Default`, `Clone`,
 //! `Write`. (the latter depends on enabled-by-default `std` crate feature)