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 != ""