bug#74630: 31.0.50; emacs-mail-verify

[Eli Zaretskii <eliz@gnu.org>]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 01 Dec 2024 00:39:00 -0500
> 
> 
> The doc string of `emacs-mail-verify' does not say how it
> indicates that the signature is valid, or how it indicates
> that the signature is not valid.

I guess you meant epa-mail-verify?

> Would someone please add that to its doc string?

Not sure what you expected the doc string to say.  Would the below be
enough?

  Verify OpenPGP cleartext signed messages in the current buffer.
  The buffer is expected to contain a mail message.

  If the verification fails, the command signals an error.

The last sentence describes the following snippet from
epa-verify-region, which epa-mail-verify calls:

    (unless (epg-context-result-for context 'verify)
      (error "Unable to verify region"))

There are also other reasons to signal an error, e.g. if there are no
"-----BEGIN PGP SIGNED MESSAGE-----" line.  But eventually, all of the
problems cause an error.

If this is somehow not detailed enough, then I'm afraid someone else,
who knows the code, will have to improve the doc string, because I
could see no clear description in the code what values could the
context-result have and what is the meaning of each result.  Maybe I
missed something.