From 1dcdad9da141e91ca8557f1480abb59e39d14006 Mon Sep 17 00:00:00 2001
From: Winni Neessen <wn@neessen.net>
Date: Sat, 5 Oct 2024 13:56:47 +0200
Subject: [PATCH] Enhance address header methods with detailed documentation

Updated comments in `header.go` and `msg.go` to provide more detailed explanations and references to RFC 5322. This improves clarity on how headers are set and utilized, and the conditions under which they operate.
---
 header.go |  7 +++++--
 msg.go    | 26 +++++++++++++++++++++-----
 2 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/header.go b/header.go
index d96271a..2b25cd2 100644
--- a/header.go
+++ b/header.go
@@ -105,8 +105,11 @@ const (
 	// HeaderCc is the "Carbon Copy" header field.
 	HeaderCc AddrHeader = "Cc"
 
-	// HeaderEnvelopeFrom is the envelope FROM header field. It is not included in the mail body but only used by
-	// the Client for the envelope.
+	// HeaderEnvelopeFrom is the envelope FROM header field.
+	//
+	// It is generally not included in the mail body but only used by the Client for the communication with the
+	// SMTP server. If the Msg has no "FROM" address set in the mail body, the msgWriter will try to use the
+	// envelope from address, if this has been set for the Msg.
 	HeaderEnvelopeFrom AddrHeader = "EnvelopeFrom"
 
 	// HeaderFrom is the "From" header field.
diff --git a/msg.go b/msg.go
index 995e93f..7e15192 100644
--- a/msg.go
+++ b/msg.go
@@ -338,7 +338,13 @@ func (m *Msg) SetGenHeaderPreformatted(header Header, value string) {
 	m.preformHeader[header] = value
 }
 
-// SetAddrHeader sets an address related header field of the Msg
+// SetAddrHeader sets the specified AddrHeader for the Msg to the given values.
+//
+// Addresses are parsed according to RFC 5322. If parsing of ANY of the provided values fails,
+// and error is returned. If you cannot guarantee that all provided values are valid, you can
+// use SetAddrHeaderIgnoreInvalid instead, which will skip any parsing error silently.
+//
+// https://datatracker.ietf.org/doc/html/rfc5322#section-3.4
 func (m *Msg) SetAddrHeader(header AddrHeader, values ...string) error {
 	if m.addrHeader == nil {
 		m.addrHeader = make(map[AddrHeader][]*mail.Address)
@@ -362,8 +368,12 @@ func (m *Msg) SetAddrHeader(header AddrHeader, values ...string) error {
 	return nil
 }
 
-// SetAddrHeaderIgnoreInvalid sets an address related header field of the Msg and ignores invalid address
-// in the validation process
+// SetAddrHeaderIgnoreInvalid sets the specified AddrHeader for the Msg to the given values.
+//
+// Addresses are parsed according to RFC 5322. If parsing of ANY of the provided values fails,
+// the error is ignored and the address omiitted from the address list.
+//
+// https://datatracker.ietf.org/doc/html/rfc5322#section-3.4
 func (m *Msg) SetAddrHeaderIgnoreInvalid(header AddrHeader, values ...string) {
 	var addresses []*mail.Address
 	for _, addrVal := range values {
@@ -376,8 +386,14 @@ func (m *Msg) SetAddrHeaderIgnoreInvalid(header AddrHeader, values ...string) {
 	m.addrHeader[header] = addresses
 }
 
-// EnvelopeFrom takes and validates a given mail address and sets it as envelope "FROM"
-// addrHeader of the Msg
+// EnvelopeFrom sets the envelope from address for the Msg.
+//
+// The HeaderEnvelopeFrom address is generally not included in the mail body but only used by the Client for the
+// communication with the SMTP server. If the Msg has no "FROM" address set in the mail body, the msgWriter will
+// try to use the envelope from address, if this has been set for the Msg. The provided address is validated
+// according to RFC 5322 and will return an error if the validation fails.
+//
+// https://datatracker.ietf.org/doc/html/rfc5322#section-3.4
 func (m *Msg) EnvelopeFrom(from string) error {
 	return m.SetAddrHeader(HeaderEnvelopeFrom, from)
 }