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.

2 files changed, 28 insertions, 2 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index e1aab1a78bf..9fa9d0c5076 100644
--- 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 c733a273988..ddea03933c4 100644
--- 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