From: Stephan Bosch <stephan.bosch@open-xchange.com>
Date: Sat, 14 Sep 2019 16:27:08 +0000 (+0200)
Subject: lib-smtp: smtp-address - Document the parse functions.
X-Git-Tag: 2.3.9~134
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=d3153559f28faa61bd3c3c9043e60d88387c5568;p=thirdparty%2Fdovecot%2Fcore.git

lib-smtp: smtp-address - Document the parse functions.
---

diff --git a/src/lib-smtp/smtp-address.h b/src/lib-smtp/smtp-address.h
index 60850eff3f..a7e7105598 100644
--- a/src/lib-smtp/smtp-address.h
+++ b/src/lib-smtp/smtp-address.h
@@ -28,19 +28,42 @@ ARRAY_DEFINE_TYPE(smtp_address_const, const struct smtp_address *);
  * SMTP address parsing
  */
 
+
+/* Parse the RFC 5321 address from the provided mailbox string. Returns 1 when
+   the address was parsed successfully and -1 upon error. The address is
+   returned in address_r. When address_r is NULL, the provided string will be
+   verified for validity as a mailbox only. */
 int smtp_address_parse_mailbox(pool_t pool, const char *mailbox,
 			       enum smtp_address_parse_flags flags,
 			       struct smtp_address **address_r,
 			       const char **error_r) ATTR_NULL(4, 5);
+/* Parse the RFC 5321 address from the provided path string. Returns 1 when
+   the address was parsed successfully and -1 upon error. The address is
+   returned in address_r. When address_r is NULL, the provided string will be
+   verified for validity as a path only. The endp_r parameter is used to
+   return a pointer to the end of the path string, so that the caller can
+   continue parsing from there. */
 int smtp_address_parse_path_full(pool_t pool, const char *path,
 				 enum smtp_address_parse_flags flags,
 				 struct smtp_address **address_r,
 				 const char **error_r, const char **endp_r)
 				 ATTR_NULL(4, 5, 6);
+/* Parse the RFC 5321 address from the provided path string. Returns 1 when
+   the address was parsed successfully and -1 upon error. The address is
+   returned in address_r. When address_r is NULL, the provided string will be
+   verified for validity as a path only. */
 int smtp_address_parse_path(pool_t pool, const char *path,
 			    enum smtp_address_parse_flags flags,
 			    struct smtp_address **address_r,
 			    const char **error_r) ATTR_NULL(4, 5);
+/* Parse the RFC 5321 address from the provided username string. A username
+   string is not strictly parsed as an RFC 5321 mailbox; it allows a more
+   lenient syntax. If the address obtained from splitting the string at the last
+   `@' can be encoded back into a valid RFC 5321 mailbox string, parsing the
+   username will succeeded. Returns 1 when the address was parsed successfully
+   and -1 upon error. The address is returned in address_r. When address_r is
+   NULL, the provided string will be verified for validity as a username only.
+ */
 int smtp_address_parse_username(pool_t pool, const char *username,
 				struct smtp_address **address_r,
 				const char **error_r) ATTR_NULL(3, 4);