try_sign_digest() is confusing.

[Firstyear]

As of 3.0.0 the try_sign_digest method is now confusing enough to be unusable.

Previously in 2.x try_sign_digest took a Digest output for signing per https://docs.rs/signature/2.3.0-pre.7/signature/trait.DigestSigner.html

However in 3.x this now takes an fn mut, and it's not clear how this works. To make matters worse the doc comments are practically identical. This leads to update errors such as:

error[E0277]: expected a `Fn(&mut _)` closure, found `sha2::Sha256`
    --> src/lib.rs:1010:30
     |
1010 |             .try_sign_digest(digest)
     |              --------------- ^^^^^^ expected an `Fn(&mut _)` closure, found `sha2::Sha256`
     |              |
     |              required by a bound introduced by this call
     |
     = help: the trait `for<'a> Fn(&'a mut _)` is not implemented for `sha2::Sha256`
note: required by a bound in `try_sign_digest`
    --> /Users/william/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/signature-3.0.0/src/signer.rs:110:27
     |
 110 |     fn try_sign_digest<F: Fn(&mut D) -> Result<(), Error>>(&self, f: F) -> Result<S, Error>;
     |                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `DigestSigner::try_sign_digest`

But there is no clear or actionable method to proceed as there is no way to pass the digest to this function.

[tarcieri]

@Firstyear we changed the purpose of DigestSigner in this release. The previous DigestSigner API only supported "prehash" / Initialize-Update-Finalize (IUF) constructions, but we have since added PrehashSigner which is a lower-level API specifically for this use case. If you're having trouble with the new DigestSigner API, I might suggest migrating to PrehashSigner instead.

The new DigestSigner API is intended to be more general and supports constructions that do their own internal initialization, including the ML-DSA "external mu" pattern and non-prehash Ed25519.

[Firstyear]

I think this is another example where the documentation of the api was really lacking. I don't think https://docs.rs/signature/latest/signature/trait.DigestSigner.html was clear about the upgrade path here, or examples of how to use the new api. I think it's very easy as the library developer to "know" how this is meant to work but from the outside it did stump me for a while til I look through example code.