wneessen/go-mail
1
1
Fork 0
mirror of https://github.com/wneessen/go-mail.git synced 2024-11-15 02:12:55 +01:00
Code Issues Projects Releases Packages Wiki Activity

Add detailed parameter and return descriptions to msg.go

Browse source 
Enhanced function documentation by adding detailed descriptions of parameters and return values for various methods. This clarifies expected inputs and outputs, improving code readability and maintainability.
This commit is contained in:
Winni Neessen 2024-10-06 00:25:15 +02:00
parent 864c593208
commit eafb9cb17e
Signed by: wneessen
GPG key ID: 385AC9889632126E
1 changed files with 56 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

67
msg.go
View file

@ -48,9 +48,11 @@ const (
// NoPGP indicates that a message should not be treated as PGP encrypted or signed and is the default value // NoPGP indicates that a message should not be treated as PGP encrypted or signed and is the default value
// for a message // for a message
NoPGP PGPType = iota NoPGP PGPType = iota
// PGPEncrypt indicates that a message should be treated as PGP encrypted. This works closely together with // PGPEncrypt indicates that a message should be treated as PGP encrypted. This works closely together with
// the corresponding go-mail-middleware. // the corresponding go-mail-middleware.
PGPEncrypt PGPEncrypt
// PGPSignature indicates that a message should be treated as PGP signed. This works closely together with // PGPSignature indicates that a message should be treated as PGP signed. This works closely together with
// the corresponding go-mail-middleware. // the corresponding go-mail-middleware.
PGPSignature PGPSignature
@ -1018,6 +1020,9 @@ func (m *Msg) GetMessageID() string {
// to track and reference the message. There are no validations performed on the input messageID, so it should // to track and reference the message. There are no validations performed on the input messageID, so it should
// be in a suitable format for use as a Message-ID. // be in a suitable format for use as a Message-ID.
// //
// Parameters:
// - messageID: The string to set as the "Message-ID" in the message header.
//
// References: // References:
// - https://datatracker.ietf.org/doc/html/rfc5322#section-3.6.4 // - https://datatracker.ietf.org/doc/html/rfc5322#section-3.6.4
func (m *Msg) SetMessageIDWithValue(messageID string) { func (m *Msg) SetMessageIDWithValue(messageID string) {
@ -1060,6 +1065,9 @@ func (m *Msg) SetDate() {
// providing recipients with context for the timing of the email. This allows for setting a custom date // providing recipients with context for the timing of the email. This allows for setting a custom date
// rather than using the current time. // rather than using the current time.
// //
// Parameters:
// - timeVal: The time value used to set the "Date" header.
//
// References: // References:
// - https://datatracker.ietf.org/doc/html/rfc5322#section-3.3 // - https://datatracker.ietf.org/doc/html/rfc5322#section-3.3
// - https://datatracker.ietf.org/doc/html/rfc1123 // - https://datatracker.ietf.org/doc/html/rfc1123
@ -1074,7 +1082,11 @@ func (m *Msg) SetDateWithValue(timeVal time.Time) {
// "X-Priority", and "X-MSMail-Priority" headers accordingly, providing email clients with information on // "X-Priority", and "X-MSMail-Priority" headers accordingly, providing email clients with information on
// how to prioritize the message. This allows the sender to indicate the significance of the email to recipients. // how to prioritize the message. This allows the sender to indicate the significance of the email to recipients.
// //
// https://datatracker.ietf.org/doc/html/rfc2156 // Parameters:
// - importance: The Importance value that determines the priority of the email message.
//
// References:
// - https://datatracker.ietf.org/doc/html/rfc2156
func (m *Msg) SetImportance(importance Importance) { func (m *Msg) SetImportance(importance Importance) {
if importance == ImportanceNormal { if importance == ImportanceNormal {
return return
@ -1091,7 +1103,11 @@ func (m *Msg) SetImportance(importance Importance) {
// header provides recipients with information about the organization that is sending the message. // header provides recipients with information about the organization that is sending the message.
// This can help establish context and credibility for the email communication. // This can help establish context and credibility for the email communication.
// //
// https://datatracker.ietf.org/doc/html/rfc5322#section-3.4 // Parameters:
// - org: The name of the organization to be set in the "Organization" header.
//
// References:
// - https://datatracker.ietf.org/doc/html/rfc5322#section-3.4
func (m *Msg) SetOrganization(org string) { func (m *Msg) SetOrganization(org string) {
m.SetGenHeader(HeaderOrganization, org) m.SetGenHeader(HeaderOrganization, org)
} }
@ -1103,7 +1119,11 @@ func (m *Msg) SetOrganization(org string) {
// or application that generated the message. This can be useful for identifying the source of the email, // or application that generated the message. This can be useful for identifying the source of the email,
// particularly for troubleshooting or filtering purposes. // particularly for troubleshooting or filtering purposes.
// //
// https://datatracker.ietf.org/doc/html/rfc5322#section-3.6.7 // Parameters:
// - userAgent: The user agent or mailer software to be set in the "User-Agent" and "X-Mailer" headers.
//
// References:
// - https://datatracker.ietf.org/doc/html/rfc5322#section-3.6.7
func (m *Msg) SetUserAgent(userAgent string) { func (m *Msg) SetUserAgent(userAgent string) {
m.SetGenHeader(HeaderUserAgent, userAgent) m.SetGenHeader(HeaderUserAgent, userAgent)
m.SetGenHeader(HeaderXMailer, userAgent) m.SetGenHeader(HeaderXMailer, userAgent)
@ -1114,6 +1134,9 @@ func (m *Msg) SetUserAgent(userAgent string) {
// This method checks the internal state of the message to determine if it has been successfully // This method checks the internal state of the message to determine if it has been successfully
// delivered. It returns true if the message is marked as delivered and false otherwise. // delivered. It returns true if the message is marked as delivered and false otherwise.
// This can be useful for tracking the status of the email communication. // This can be useful for tracking the status of the email communication.
//
// Returns:
// - A boolean value indicating the delivery status of the message (true if delivered, false otherwise).
func (m *Msg) IsDelivered() bool { func (m *Msg) IsDelivered() bool {
return m.isDelivered return m.isDelivered
} }
@ -1126,7 +1149,11 @@ func (m *Msg) IsDelivered() bool {
// will be returned indicating the parsing failure. If the "Disposition-Notification-To" header // will be returned indicating the parsing failure. If the "Disposition-Notification-To" header
// is already set, it will be updated with the new list of addresses. // is already set, it will be updated with the new list of addresses.
// //
// https://datatracker.ietf.org/doc/html/rfc8098 // Parameters:
// - rcpts: One or more recipient email addresses to request the MDN from.
//
// References:
// - https://datatracker.ietf.org/doc/html/rfc8098
func (m *Msg) RequestMDNTo(rcpts ...string) error { func (m *Msg) RequestMDNTo(rcpts ...string) error {
var addresses []string var addresses []string
for _, addrVal := range rcpts { for _, addrVal := range rcpts {
@ -1149,7 +1176,12 @@ func (m *Msg) RequestMDNTo(rcpts ...string) error {
// Address validation is performed according to RFC 5322 standards. If the provided address is invalid, // Address validation is performed according to RFC 5322 standards. If the provided address is invalid,
// an error will be returned. This method internally calls RequestMDNTo to handle the actual setting of the header. // an error will be returned. This method internally calls RequestMDNTo to handle the actual setting of the header.
// //
// https://datatracker.ietf.org/doc/html/rfc8098 // Parameters:
// - name: The name of the recipient for the MDN request.
// - addr: The email address of the recipient for the MDN request.
//
// References:
// - https://datatracker.ietf.org/doc/html/rfc8098
func (m *Msg) RequestMDNToFormat(name, addr string) error { func (m *Msg) RequestMDNToFormat(name, addr string) error {
return m.RequestMDNTo(fmt.Sprintf(`%s <%s>`, name, addr)) return m.RequestMDNTo(fmt.Sprintf(`%s <%s>`, name, addr))
} }
@ -1161,7 +1193,11 @@ func (m *Msg) RequestMDNToFormat(name, addr string) error {
// an error will be returned indicating the parsing failure. If the "Disposition-Notification-To" // an error will be returned indicating the parsing failure. If the "Disposition-Notification-To"
// header is already set, the new recipient will be added to the existing list. // header is already set, the new recipient will be added to the existing list.
// //
// https://datatracker.ietf.org/doc/html/rfc8098 // Parameters:
// - rcpt: The recipient email address to add to the "Disposition-Notification-To" header.
//
// References:
// - https://datatracker.ietf.org/doc/html/rfc8098
func (m *Msg) RequestMDNAddTo(rcpt string) error { func (m *Msg) RequestMDNAddTo(rcpt string) error {
address, err := mail.ParseAddress(rcpt) address, err := mail.ParseAddress(rcpt)
if err != nil { if err != nil {
@ -1184,7 +1220,12 @@ func (m *Msg) RequestMDNAddTo(rcpt string) error {
// according to RFC 5322 standards. If the provided address is invalid, an error will be returned. // according to RFC 5322 standards. If the provided address is invalid, an error will be returned.
// This method internally calls RequestMDNAddTo to handle the actual addition of the recipient. // This method internally calls RequestMDNAddTo to handle the actual addition of the recipient.
// //
// https://datatracker.ietf.org/doc/html/rfc8098 // Parameters:
// - name: The name of the recipient to add to the "Disposition-Notification-To" header.
// - addr: The email address of the recipient to add to the "Disposition-Notification-To" header.
//
// References:
// - https://datatracker.ietf.org/doc/html/rfc8098
func (m *Msg) RequestMDNAddToFormat(name, addr string) error { func (m *Msg) RequestMDNAddToFormat(name, addr string) error {
return m.RequestMDNAddTo(fmt.Sprintf(`"%s" <%s>`, name, addr)) return m.RequestMDNAddTo(fmt.Sprintf(`"%s" <%s>`, name, addr))
} }
@ -1204,7 +1245,8 @@ func (m *Msg) RequestMDNAddToFormat(name, addr string) error {
// Returns: // Returns:
// - The sender's address as a string and an error if applicable. // - The sender's address as a string and an error if applicable.
// //
// https://datatracker.ietf.org/doc/html/rfc5322#section-3.6.2 // References:
// - https://datatracker.ietf.org/doc/html/rfc5322#section-3.6.2
func (m *Msg) GetSender(useFullAddr bool) (string, error) { func (m *Msg) GetSender(useFullAddr bool) (string, error) {
from, ok := m.addrHeader[HeaderEnvelopeFrom] from, ok := m.addrHeader[HeaderEnvelopeFrom]
if !ok || len(from) == 0 { if !ok || len(from) == 0 {
@ -1230,7 +1272,8 @@ func (m *Msg) GetSender(useFullAddr bool) (string, error) {
// - If there are no recipient addresses set, it will return an error indicating no recipient // - If there are no recipient addresses set, it will return an error indicating no recipient
// addresses are available. // addresses are available.
// //
// https://datatracker.ietf.org/doc/html/rfc5322#section-3.6.3 // References:
// - https://datatracker.ietf.org/doc/html/rfc5322#section-3.6.3
func (m *Msg) GetRecipients() ([]string, error) { func (m *Msg) GetRecipients() ([]string, error) {
var rcpts []string var rcpts []string
for _, addressType := range []AddrHeader{HeaderTo, HeaderCc, HeaderBcc} { for _, addressType := range []AddrHeader{HeaderTo, HeaderCc, HeaderBcc} {
@ -1262,7 +1305,8 @@ func (m *Msg) GetRecipients() ([]string, error) {
// - A slice of pointers to mail.Address structures containing the addresses from the specified // - A slice of pointers to mail.Address structures containing the addresses from the specified
// header. // header.
// //
// https://datatracker.ietf.org/doc/html/rfc5322#section-3.6 // References:
// - https://datatracker.ietf.org/doc/html/rfc5322#section-3.6
func (m *Msg) GetAddrHeader(header AddrHeader) []*mail.Address { func (m *Msg) GetAddrHeader(header AddrHeader) []*mail.Address {
return m.addrHeader[header] return m.addrHeader[header]
} }
@ -1281,7 +1325,8 @@ func (m *Msg) GetAddrHeader(header AddrHeader) []*mail.Address {
// Returns: // Returns:
// - A slice of strings containing the formatted addresses from the specified header. // - A slice of strings containing the formatted addresses from the specified header.
// //
// https://datatracker.ietf.org/doc/html/rfc5322#section-3.6 // References:
// - https://datatracker.ietf.org/doc/html/rfc5322#section-3.6
func (m *Msg) GetAddrHeaderString(header AddrHeader) []string { func (m *Msg) GetAddrHeaderString(header AddrHeader) []string {
var addresses []string var addresses []string
for _, mh := range m.addrHeader[header] { for _, mh := range m.addrHeader[header] {