From ac7fa5771aa141a375c763b10986662128273b31 Mon Sep 17 00:00:00 2001 From: Winni Neessen Date: Sun, 6 Oct 2024 16:16:49 +0200 Subject: [PATCH] Refactor documentation and enhance comments Updated documentation for the `File` struct and its methods, providing clearer explanations and detailed parameter and return descriptions. Improved readability and consistency of comments across the codebase. --- file.go | 91 +++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 75 insertions(+), 16 deletions(-) diff --git a/file.go b/file.go index 77e516c..8866d97 100644 --- a/file.go +++ b/file.go @@ -12,8 +12,12 @@ import ( // FileOption is a function type used to modify properties of a File type FileOption func(*File) -// 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. +// File represents a file with properties such as content type, description, encoding, headers, name, and +// a writer function. +// +// This struct can represent either an attachment or an embedded file in a Msg, and it stores relevant +// metadata such as content type and encoding, as well as a function to write the file's content to an +// io.Writer. type File struct { ContentType ContentType Desc string @@ -23,7 +27,16 @@ type File struct { Writer func(w io.Writer) (int64, error) } -// WithFileContentID sets the "Content-ID" header in the File's MIME headers to the specified id. +// WithFileContentID sets the "Content-ID" header in the File's MIME headers to the specified ID. +// +// This function updates the File's MIME headers by setting the "Content-ID" to the provided string value, +// allowing the file to be referenced by this ID within the MIME structure. +// +// Parameters: +// - id: A string representing the content ID to be set in the "Content-ID" header. +// +// Returns: +// - A FileOption function that updates the File's "Content-ID" header. func WithFileContentID(id string) FileOption { return func(f *File) { f.Header.Set(HeaderContentID.String(), id) @@ -31,27 +44,51 @@ func WithFileContentID(id string) FileOption { } // WithFileName sets the name of a File to the provided value. +// +// This function assigns the specified name to the File, updating its Name field. +// +// Parameters: +// - name: A string representing the name to be assigned to the File. +// +// Returns: +// - A FileOption function that sets the File's name. func WithFileName(name string) FileOption { return func(f *File) { f.Name = name } } -// WithFileDescription sets an optional file description for the File. The description is used in the -// Content-Description header of the MIME output. +// WithFileDescription sets an optional description for the File, which is used in the Content-Description +// header of the MIME output. +// +// This function updates the File's description, allowing an additional text description to be added to +// the MIME headers for the file. +// +// Parameters: +// - description: A string representing the description to be set in the Content-Description header. +// +// Returns: +// - A FileOption function that sets the File's description. func WithFileDescription(description string) FileOption { return func(f *File) { f.Desc = description } } -// WithFileEncoding sets the encoding type for a file. +// 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. +// This function allows the specification of an encoding type for the file, typically used for attachments +// or embedded files. By default, Base64 encoding should be used, but this function can override the +// default if needed. // -// 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. +// Note: Quoted-printable encoding (EncodingQP) must never be used for attachments or embeds. If EncodingQP +// is passed to this function, it will be ignored and the encoding will remain unchanged. +// +// Parameters: +// - encoding: The Encoding type to be assigned to the File, unless it's EncodingQP. +// +// Returns: +// - A FileOption function that sets the File's encoding. func WithFileEncoding(encoding Encoding) FileOption { return func(f *File) { if encoding == EncodingQP { @@ -63,22 +100,44 @@ func WithFileEncoding(encoding Encoding) FileOption { // WithFileContentType sets the content type of the File. // -// 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. +// By default, the content type is guessed based on the file type, and if no matching type is identified, +// the default "application/octet-stream" is used. This FileOption allows overriding the guessed content +// type with a specific one if required. +// +// Parameters: +// - contentType: The ContentType to be assigned to the File. +// +// Returns: +// - A FileOption function that sets the File's content type. func WithFileContentType(contentType ContentType) FileOption { return func(f *File) { f.ContentType = contentType } } -// setHeader sets the value of a given MIME header field for the File. +// setHeader sets the value of a specified MIME header field for the File. +// +// This method updates the MIME headers of the File by assigning the provided value to the specified +// header field. +// +// Parameters: +// - header: The Header field to be updated. +// - value: A string representing the value to be set for the given header. func (f *File) setHeader(header Header, value string) { f.Header.Set(string(header), value) } -// 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. +// getHeader retrieves the value of the specified MIME header field. +// +// This method returns the value of the given header and a boolean indicating whether the header was found +// in the File's MIME headers. +// +// Parameters: +// - header: The Header field whose value is to be retrieved. +// +// Returns: +// - A string containing the value of the header. +// - A boolean indicating whether the header was present (true) or not (false). func (f *File) getHeader(header Header) (string, bool) { v := f.Header.Get(string(header)) return v, v != ""