From 6ce75b19797abcf65a93307260a6688bbf76f287 Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Sat, 30 Jul 2022 13:40:59 +0200 Subject: [PATCH] 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 d1ad671b160..b7d96a1053d 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?= \" + +If you have an already-decoded address, like + + \"André \" + +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 ec719850e2e..d28b8b58438 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. -- 2.39.5