From 6ce5c2a8606d495cf4d5c559a40d06977814df8e Mon Sep 17 00:00:00 2001
From: Winni Neessen <wn@neessen.net>
Date: Sun, 6 Oct 2024 17:12:52 +0200
Subject: [PATCH] Enhance documentation for SendError methods and fields

Improved comments for better clarity and detail in SendError-related methods and fields. Updated comments provide more in-depth explanations of functionality, parameters, return values, and usage.
---
 senderror.go | 75 +++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 65 insertions(+), 10 deletions(-)

diff --git a/senderror.go b/senderror.go
index 90c8c4a..1943e28 100644
--- a/senderror.go
+++ b/senderror.go
@@ -54,7 +54,11 @@ const (
 	ErrAmbiguous
 )
 
-// SendError is an error wrapper for delivery errors of the Msg
+// SendError is an error wrapper for delivery errors of the Msg.
+//
+// This struct represents an error that occurs during the delivery of a message. It holds
+// details about the affected message, a list of errors, the recipient list, and whether
+// the error is temporary or permanent. It also includes a reason code for the error.
 type SendError struct {
 	affectedMsg *Msg
 	errlist     []error
@@ -66,7 +70,16 @@ type SendError struct {
 // SendErrReason represents a comparable reason on why the delivery failed
 type SendErrReason int
 
-// Error implements the error interface for the SendError type
+// Error implements the error interface for the SendError type.
+//
+// This function returns a detailed error message string for the SendError, including the
+// reason for failure, list of errors, affected recipients, and the message ID of the
+// affected message (if available). If the reason is unknown (greater than 10), it returns
+// "unknown reason". The error message is built dynamically based on the content of the
+// error list, recipient list, and message ID.
+//
+// Returns:
+//   - A string representing the error message.
 func (e *SendError) Error() string {
 	if e.Reason > 10 {
 		return "unknown reason"
@@ -101,7 +114,17 @@ func (e *SendError) Error() string {
 	return errMessage.String()
 }
 
-// Is implements the errors.Is functionality and compares the SendErrReason
+// Is implements the errors.Is functionality and compares the SendErrReason.
+//
+// This function allows for comparison between two errors by checking if the provided
+// error matches the SendError type and, if so, compares the SendErrReason and the
+// temporary status (isTemp) of both errors.
+//
+// Parameters:
+//   - errType: The error to compare against the current SendError.
+//
+// Returns:
+//   - true if the errors have the same reason and temporary status, false otherwise.
 func (e *SendError) Is(errType error) bool {
 	var t *SendError
 	if errors.As(errType, &t) && t != nil {
@@ -110,7 +133,13 @@ func (e *SendError) Is(errType error) bool {
 	return false
 }
 
-// IsTemp returns true if the delivery error is of temporary nature and can be retried
+// IsTemp returns true if the delivery error is of a temporary nature and can be retried.
+//
+// This function checks whether the SendError indicates a temporary error, which suggests
+// that the delivery can be retried. If the SendError is nil, it returns false.
+//
+// Returns:
+//   - true if the error is temporary, false otherwise.
 func (e *SendError) IsTemp() bool {
 	if e == nil {
 		return false
@@ -118,8 +147,13 @@ func (e *SendError) IsTemp() bool {
 	return e.isTemp
 }
 
-// MessageID returns the message ID of the affected Msg that caused the error
-// If no message ID was set for the Msg, an empty string will be returned
+// MessageID returns the message ID of the affected Msg that caused the error.
+//
+// This function retrieves the message ID of the Msg associated with the SendError.
+// If no message ID was set or if the SendError or Msg is nil, it returns an empty string.
+//
+// Returns:
+//   - The message ID as a string, or an empty string if no ID is available.
 func (e *SendError) MessageID() string {
 	if e == nil || e.affectedMsg == nil {
 		return ""
@@ -127,7 +161,13 @@ func (e *SendError) MessageID() string {
 	return e.affectedMsg.GetMessageID()
 }
 
-// Msg returns the pointer to the affected message that caused the error
+// Msg returns the pointer to the affected message that caused the error.
+//
+// This function retrieves the Msg associated with the SendError. If the SendError or
+// the affectedMsg is nil, it returns nil.
+//
+// Returns:
+//   - A pointer to the Msg that caused the error, or nil if not available.
 func (e *SendError) Msg() *Msg {
 	if e == nil || e.affectedMsg == nil {
 		return nil
@@ -135,7 +175,14 @@ func (e *SendError) Msg() *Msg {
 	return e.affectedMsg
 }
 
-// String implements the Stringer interface for the SendErrReason
+// String satisfies the fmt.Stringer interface for the SendErrReason type.
+//
+// This function converts the SendErrReason into a human-readable string representation based
+// on the error type. If the error reason does not match any predefined case, it returns
+// "unknown reason".
+//
+// Returns:
+//   - A string representation of the SendErrReason.
 func (r SendErrReason) String() string {
 	switch r {
 	case ErrGetSender:
@@ -164,8 +211,16 @@ func (r SendErrReason) String() string {
 	return "unknown reason"
 }
 
-// isTempError checks the given SMTP error and returns true if the given error is of temporary nature
-// and should be retried
+// isTempError checks if the given SMTP error is of a temporary nature and should be retried.
+//
+// This function inspects the error message and returns true if the first character of the
+// error message is '4', indicating a temporary SMTP error that can be retried.
+//
+// Parameters:
+//   - err: The error to check.
+//
+// Returns:
+//   - true if the error is temporary, false otherwise.
 func isTempError(err error) bool {
 	return err.Error()[0] == '4'
 }