Refactor SMTP client comment and function documentation

Updated function comments across client.go to improve clarity and consistency. Added missing details on error handling and context usage for `DialAndSendWithContext` and ensured all functions contain relevant, detailed descriptions.
This commit is contained in:
Winni Neessen 2024-10-04 23:23:16 +02:00
parent adcb8ac41d
commit 48b469faf7
Signed by: wneessen
GPG key ID: 385AC9889632126E

View file

@ -715,9 +715,9 @@ func (c *Client) DialWithContext(dialCtx context.Context) error {
return nil return nil
} }
// Close closes the Client connection // Close terminates the connection to the SMTP server, returning an error if the disconnection fails.
func (c *Client) Close() error {
// If the connection is already closed, we considered this a no-op and disregard any error. // If the connection is already closed, we considered this a no-op and disregard any error.
func (c *Client) Close() error {
if !c.smtpClient.HasConnection() { if !c.smtpClient.HasConnection() {
return nil return nil
} }
@ -728,7 +728,7 @@ func (c *Client) Close() error {
return nil return nil
} }
// Reset sends the RSET command to the SMTP client // Reset sends an SMTP RSET command to reset the state of the current SMTP session.
func (c *Client) Reset() error { func (c *Client) Reset() error {
if err := c.checkConn(); err != nil { if err := c.checkConn(); err != nil {
return err return err
@ -740,19 +740,24 @@ func (c *Client) Reset() error {
return nil return nil
} }
// DialAndSend establishes a connection to the SMTP server with a // DialAndSend establishes a connection to the server and sends out the provided Msg. It will call
// default context.Background and sends the mail // DialAndSendWithContext with an empty Context.Background
func (c *Client) DialAndSend(messages ...*Msg) error { func (c *Client) DialAndSend(messages ...*Msg) error {
ctx := context.Background() ctx := context.Background()
return c.DialAndSendWithContext(ctx, messages...) return c.DialAndSendWithContext(ctx, messages...)
} }
// DialAndSendWithContext establishes a connection to the SMTP server with a // DialAndSendWithContext establishes a connection to the SMTP server using DialWithContext using the
// custom context and sends the mail // provided context.Context, then sends out the given Msg. After successful delivery the Client
// will close the connection to the server.
func (c *Client) DialAndSendWithContext(ctx context.Context, messages ...*Msg) error { func (c *Client) DialAndSendWithContext(ctx context.Context, messages ...*Msg) error {
if err := c.DialWithContext(ctx); err != nil { if err := c.DialWithContext(ctx); err != nil {
return fmt.Errorf("dial failed: %w", err) return fmt.Errorf("dial failed: %w", err)
} }
defer func() {
_ = c.Close()
}()
if err := c.Send(messages...); err != nil { if err := c.Send(messages...); err != nil {
return fmt.Errorf("send failed: %w", err) return fmt.Errorf("send failed: %w", err)
} }