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 60850eff3fe8b5b4aff12d14e1b3e34102c2b430..a7e710559866c56b1163c6f4d9507ba0432b8709 100644 (file)
--- 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);