From e640f2df4612fe55656f8036292dc818b9ef45d0 Mon Sep 17 00:00:00 2001 From: Winni Neessen Date: Sun, 6 Oct 2024 16:54:18 +0200 Subject: [PATCH] Add detailed comments and return descriptions to `Part` methods Enhanced the documentation of `Part` struct and its methods to provide clearer explanations, including parameter and return descriptions. This improves code readability and helps developers understand the functionality and usage of each method. --- part.go | 136 ++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 118 insertions(+), 18 deletions(-) diff --git a/part.go b/part.go index 7c76b7d..5be8059 100644 --- a/part.go +++ b/part.go @@ -12,7 +12,11 @@ import ( // PartOption returns a function that can be used for grouping Part options type PartOption func(*Part) -// Part is a part of the Msg +// Part is a part of the Msg. +// +// This struct represents a single part of a multipart message. Each part has a content type, +// charset, optional description, encoding, and a function to write its content to an io.Writer. +// It also includes a flag to mark the part as deleted. type Part struct { contentType ContentType charset Charset @@ -22,7 +26,14 @@ type Part struct { writeFunc func(io.Writer) (int64, error) } -// GetContent executes the WriteFunc of the Part and returns the content as byte slice +// GetContent executes the WriteFunc of the Part and returns the content as a byte slice. +// +// This function runs the part's writeFunc to write its content into a buffer and then returns +// the content as a byte slice. If an error occurs during the writing process, it is returned. +// +// Returns: +// - A byte slice containing the part's content. +// - An error if the writeFunc encounters an issue. func (p *Part) GetContent() ([]byte, error) { var b bytes.Buffer if _, err := p.writeFunc(&b); err != nil { @@ -31,83 +42,172 @@ func (p *Part) GetContent() ([]byte, error) { return b.Bytes(), nil } -// GetCharset returns the currently set Charset of the Part +// GetCharset returns the currently set Charset of the Part. +// +// This function returns the Charset that is currently set for the Part. +// +// Returns: +// - The Charset of the Part. func (p *Part) GetCharset() Charset { return p.charset } -// GetContentType returns the currently set ContentType of the Part +// GetContentType returns the currently set ContentType of the Part. +// +// This function returns the ContentType that is currently set for the Part. +// +// Returns: +// - The ContentType of the Part. func (p *Part) GetContentType() ContentType { return p.contentType } -// GetEncoding returns the currently set Encoding of the Part +// GetEncoding returns the currently set Encoding of the Part. +// +// This function returns the Encoding that is currently set for the Part. +// +// Returns: +// - The Encoding of the Part. func (p *Part) GetEncoding() Encoding { return p.encoding } -// GetWriteFunc returns the currently set WriterFunc of the Part +// GetWriteFunc returns the currently set WriteFunc of the Part. +// +// This function returns the WriteFunc that is currently set for the Part, which writes +// the part's content to an io.Writer. +// +// Returns: +// - The WriteFunc of the Part, which is a function that takes an io.Writer and returns +// the number of bytes written and an error (if any). func (p *Part) GetWriteFunc() func(io.Writer) (int64, error) { return p.writeFunc } -// GetDescription returns the currently set Content-Description of the Part +// GetDescription returns the currently set Content-Description of the Part. +// +// This function returns the Content-Description that is currently set for the Part. +// +// Returns: +// - The Content-Description of the Part as a string. func (p *Part) GetDescription() string { return p.description } -// SetContent overrides the content of the Part with the given string +// SetContent overrides the content of the Part with the given string. +// +// This function sets the content of the Part by creating a new writeFunc that writes the +// provided string content to an io.Writer. +// +// Parameters: +// - content: The string that will replace the current content of the Part. func (p *Part) SetContent(content string) { buffer := bytes.NewBufferString(content) p.writeFunc = writeFuncFromBuffer(buffer) } -// SetContentType overrides the ContentType of the Part +// SetContentType overrides the ContentType of the Part. +// +// This function sets a new ContentType for the Part, replacing the existing one. +// +// Parameters: +// - contentType: The new ContentType to be set for the Part. func (p *Part) SetContentType(contentType ContentType) { p.contentType = contentType } -// SetCharset overrides the Charset of the Part +// SetCharset overrides the Charset of the Part. +// +// This function sets a new Charset for the Part, replacing the existing one. +// +// Parameters: +// - charset: The new Charset to be set for the Part. func (p *Part) SetCharset(charset Charset) { p.charset = charset } -// SetEncoding creates a new mime.WordEncoder based on the encoding setting of the message +// SetEncoding creates a new mime.WordEncoder based on the encoding setting of the message. +// +// This function sets a new Encoding for the Part, replacing the existing one. +// +// Parameters: +// - encoding: The new Encoding to be set for the Part. func (p *Part) SetEncoding(encoding Encoding) { p.encoding = encoding } -// SetDescription overrides the Content-Description of the Part +// SetDescription overrides the Content-Description of the Part. +// +// This function sets a new Content-Description for the Part, replacing the existing one. +// +// Parameters: +// - description: The new Content-Description to be set for the Part. func (p *Part) SetDescription(description string) { p.description = description } -// SetWriteFunc overrides the WriteFunc of the Part +// SetWriteFunc overrides the WriteFunc of the Part. +// +// This function sets a new WriteFunc for the Part, replacing the existing one. The WriteFunc +// is responsible for writing the Part's content to an io.Writer. +// +// Parameters: +// - writeFunc: A function that writes the Part's content to an io.Writer and returns +// the number of bytes written and an error (if any). func (p *Part) SetWriteFunc(writeFunc func(io.Writer) (int64, error)) { p.writeFunc = writeFunc } -// Delete removes the current part from the parts list of the Msg by setting the -// isDeleted flag to true. The msgWriter will skip it then +// Delete removes the current part from the parts list of the Msg by setting the isDeleted flag to true. +// +// This function marks the Part as deleted by setting the isDeleted flag to true. The msgWriter +// will skip over this Part during processing. func (p *Part) Delete() { p.isDeleted = true } -// WithPartCharset overrides the default Part charset +// WithPartCharset overrides the default Part charset. +// +// This function returns a PartOption that allows the charset of a Part to be overridden +// with the specified Charset. +// +// Parameters: +// - charset: The Charset to be set for the Part. +// +// Returns: +// - A PartOption function that sets the Part's charset. func WithPartCharset(charset Charset) PartOption { return func(p *Part) { p.charset = charset } } -// WithPartEncoding overrides the default Part encoding +// WithPartEncoding overrides the default Part encoding. +// +// This function returns a PartOption that allows the encoding of a Part to be overridden +// with the specified Encoding. +// +// Parameters: +// - encoding: The Encoding to be set for the Part. +// +// Returns: +// - A PartOption function that sets the Part's encoding. func WithPartEncoding(encoding Encoding) PartOption { return func(p *Part) { p.encoding = encoding } } -// WithPartContentDescription overrides the default Part Content-Description +// WithPartContentDescription overrides the default Part Content-Description. +// +// This function returns a PartOption that allows the Content-Description of a Part +// to be overridden with the specified description. +// +// Parameters: +// - description: The Content-Description to be set for the Part. +// +// Returns: +// - A PartOption function that sets the Part's Content-Description. func WithPartContentDescription(description string) PartOption { return func(p *Part) { p.description = description