epg: doc improvement for verify functions

* epg.el (epg-verify-file): Add a comment saying that it does not
notify verification error as a return value nor a signal.
(epg-verify-string): Ditto.

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index e1aab1a..9fa9d0c 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,9 @@
+2013-10-03  Daiki Ueno  <ueno@gnu.org>
+
+       * epg.el (epg-verify-file): Add a comment saying that it does not
+       notify verification error as a return value nor a signal.
+       (epg-verify-string): Ditto.
+
 2013-10-02  Kevin Rodgers  <kevin.d.rodgers@gmail.com>
 
        * progmodes/compile.el (compilation-start): Try globbing the arg to

diff --git a/lisp/epg.el b/lisp/epg.el
index c733a27..ddea039 100644 (file)
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -2219,7 +2219,17 @@ SIGNED-TEXT and PLAIN are also a file if they are specified.
 For a detached signature, both SIGNATURE and SIGNED-TEXT should be
 string.  For a normal or a cleartext signature, SIGNED-TEXT should be
 nil.  In the latter case, if PLAIN is specified, the plaintext is
-stored into the file after successful verification."
+stored into the file after successful verification.
+
+Note that this function does not return verification result as t
+or nil, nor signal error on failure.  That's a design decision to
+handle the case where SIGNATURE has multiple signature.
+
+To check the verification results, use `epg-context-result-for' as follows:
+
+\(epg-context-result-for context 'verify)
+
+which will return a list of `epg-signature' object."
   (unwind-protect
       (progn
        (if plain
@@ -2246,7 +2256,17 @@ SIGNED-TEXT is a string if it is specified.
 For a detached signature, both SIGNATURE and SIGNED-TEXT should be
 string.  For a normal or a cleartext signature, SIGNED-TEXT should be
 nil.  In the latter case, this function returns the plaintext after
-successful verification."
+successful verification.
+
+Note that this function does not return verification result as t
+or nil, nor signal error on failure.  That's a design decision to
+handle the case where SIGNATURE has multiple signature.
+
+To check the verification results, use `epg-context-result-for' as follows:
+
+\(epg-context-result-for context 'verify)
+
+which will return a list of `epg-signature' object."
   (let ((coding-system-for-write 'binary)
        input-file)
     (unwind-protect