From a0a7f74121c040a4453d57061d1e3e130fee77a2 Mon Sep 17 00:00:00 2001
From: Winni Neessen <wn@neessen.net>
Date: Sat, 5 Oct 2024 11:42:21 +0200
Subject: [PATCH] Refactor file.go comments for clarity and detail

Improved comments for better readability and understanding. Enhanced descriptions for File, FileOption, and various methods, providing more context and precision. Added notes on default behaviors and specific use cases for methods where applicable.
---
 file.go | 38 +++++++++++++++++++++-----------------
 1 file changed, 21 insertions(+), 17 deletions(-)

diff --git a/file.go b/file.go
index 45e142a..77e516c 100644
--- a/file.go
+++ b/file.go
@@ -9,10 +9,11 @@ import (
 	"net/textproto"
 )
 
-// FileOption returns a function that can be used for grouping File options
+// FileOption is a function type used to modify properties of a File
 type FileOption func(*File)
 
-// File is an attachment or embedded file of the Msg
+// File represents a file with properties like content type, description, encoding, headers, name, and
+// writer function. This can either be an attachment or an embedded file for a Msg.
 type File struct {
 	ContentType ContentType
 	Desc        string
@@ -22,32 +23,35 @@ type File struct {
 	Writer      func(w io.Writer) (int64, error)
 }
 
-// WithFileContentID sets the Content-ID header for the File
+// WithFileContentID sets the "Content-ID" header in the File's MIME headers to the specified id.
 func WithFileContentID(id string) FileOption {
 	return func(f *File) {
 		f.Header.Set(HeaderContentID.String(), id)
 	}
 }
 
-// WithFileName sets the filename of the File
+// WithFileName sets the name of a File to the provided value.
 func WithFileName(name string) FileOption {
 	return func(f *File) {
 		f.Name = name
 	}
 }
 
-// WithFileDescription sets an optional file description of the File that will be
-// added as Content-Description part
+// WithFileDescription sets an optional file description for the File. The description is used in the
+// Content-Description header of the MIME output.
 func WithFileDescription(description string) FileOption {
 	return func(f *File) {
 		f.Desc = description
 	}
 }
 
-// WithFileEncoding sets the encoding of the File. By default we should always use
-// Base64 encoding but there might be exceptions, where this might come handy.
-// Please note that quoted-printable should never be used for attachments/embeds. If this
-// is provided as argument, the function will automatically override back to Base64
+// WithFileEncoding sets the encoding type for a file.
+//
+// By default one should always use Base64 encoding for attachments and embeds, but there might be exceptions in
+// which this might come handy.
+//
+// Note: that quoted-printable must never be used for attachments or embeds. If EncodingQP is provided as encoding
+// to this method, it will be automatically overwritten with EncodingB64.
 func WithFileEncoding(encoding Encoding) FileOption {
 	return func(f *File) {
 		if encoding == EncodingQP {
@@ -58,23 +62,23 @@ func WithFileEncoding(encoding Encoding) FileOption {
 }
 
 // WithFileContentType sets the content type of the File.
-// By default go-mail will try to guess the file type and its corresponding
-// content type and fall back to application/octet-stream if the file type
-// could not be guessed. In some cases, however, it might be needed to force
-// this to a specific type. For such situations this override method can
-// be used
+//
+// By default we will try to guess the file type and its corresponding content type and fall back to
+// application/octet-stream if the file type, if no matching type could be guessed. This FileOption can
+// be used to override this type, in case a specific type is required.
 func WithFileContentType(contentType ContentType) FileOption {
 	return func(f *File) {
 		f.ContentType = contentType
 	}
 }
 
-// setHeader sets header fields to a File
+// setHeader sets the value of a given MIME header field for the File.
 func (f *File) setHeader(header Header, value string) {
 	f.Header.Set(string(header), value)
 }
 
-// getHeader return header fields of a File
+// getHeader retrieves the value of the specified MIME header field. It returns the header value and a boolean
+// indicating whether the header was present or not.
 func (f *File) getHeader(header Header) (string, bool) {
 	v := f.Header.Get(string(header))
 	return v, v != ""