master 6ce75b1979: Clarify mail-header address parsing doc strings

[Lars Ingebrigtsen]

branch: master
commit 6ce75b19797abcf65a93307260a6688bbf76f287
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Clarify mail-header address parsing doc strings
    
    * lisp/mail/mail-parse.el (mail-header-parse-address-lax):
    * lisp/mail/ietf-drums.el (ietf-drums-parse-address): Clarify what
    these functions do (bug#56824).
---
 lisp/mail/ietf-drums.el | 13 +++++++++++++
 lisp/mail/mail-parse.el |  8 ++++----
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/lisp/mail/ietf-drums.el b/lisp/mail/ietf-drums.el
index d1ad671b16..b7d96a1053 100644
--- a/lisp/mail/ietf-drums.el
+++ b/lisp/mail/ietf-drums.el
@@ -189,6 +189,19 @@ the Content-Transfer-Encoding header of a mail."
 
 (defun ietf-drums-parse-address (string &optional decode)
   "Parse STRING and return a MAILBOX / DISPLAY-NAME pair.
+STRING here is supposed to be an RFC822(bis) mail address, and
+will commonly look like, for instance:
+
+  \"=?utf-8?Q?Andr=C3=A9?= <andre@example.com>\"
+
+If you have an already-decoded address, like
+
+  \"André <andre@example.com>\"
+
+this function can't be used to parse that.  Instead, use
+`mail-header-parse-address-lax' to make a guess at what's the
+name and what's the address.
+
 If DECODE, the DISPLAY-NAME will have RFC2047 decoding performed
 (that's the \"=?utf...q...=?\") stuff."
   (when decode
diff --git a/lisp/mail/mail-parse.el b/lisp/mail/mail-parse.el
index ec719850e2..d28b8b5843 100644
--- a/lisp/mail/mail-parse.el
+++ b/lisp/mail/mail-parse.el
@@ -85,10 +85,10 @@ The return value is a list with mail/name pairs."
   "Parse STRING as a mail address.
 Returns a mail/name pair.
 
-This function will first try to parse STRING as a
-standards-compliant address string, and if that fails, try to use
-heuristics to determine the email address and the name in the
-string."
+This function uses heuristics to determine the email address and
+the name in the string.  If you have an RFC822(bis)
+standards-compliant STRING, use `mail-header-parse-address'
+instead."
   (with-temp-buffer
     (insert (string-clean-whitespace string))
     ;; Find the bit with the @ and guess that that's the mail.