From 5d79ff69c34a3a685ca77a956159ae3ec93cc589 Mon Sep 17 00:00:00 2001
From: Winni Neessen <wn@neessen.net>
Date: Sun, 6 Oct 2024 17:05:04 +0200
Subject: [PATCH] Enhance and clarify Reader struct documentation

Improved documentation for the Reader struct, its methods, and error handling. Added detailed explanations for `Read`, `Error`, `Reset`, and `empty` functions to better describe their parameters, return values, and behavior.
---
 reader.go | 40 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 5 deletions(-)

diff --git a/reader.go b/reader.go
index 3c44f4c..e635e3a 100644
--- a/reader.go
+++ b/reader.go
@@ -8,19 +8,41 @@ import (
 	"io"
 )
 
-// Reader is a type that implements the io.Reader interface for a Msg
+// Reader is a type that implements the io.Reader interface for a Msg.
+//
+// This struct represents a reader that reads from a byte slice buffer. It keeps track of the
+// current read position (offset) and any initialization error. The buffer holds the data to be
+// read from the message.
 type Reader struct {
 	buffer []byte // contents are the bytes buffer[offset : len(buffer)]
 	offset int    // read at &buffer[offset], write at &buffer[len(buffer)]
 	err    error  // initialization error
 }
 
-// Error returns an error if the Reader err field is not nil
+// Error returns an error if the Reader err field is not nil.
+//
+// This function checks the Reader's err field and returns it if it is not nil. If no error
+// occurred during initialization, it returns nil.
+//
+// Returns:
+//   - The error stored in the err field, or nil if no error is present.
 func (r *Reader) Error() error {
 	return r.err
 }
 
-// Read reads the length of p of the Msg buffer to satisfy the io.Reader interface
+// Read reads the content of the Msg buffer into the provided payload to satisfy the io.Reader interface.
+//
+// This function reads data from the Reader's buffer into the provided byte slice (payload).
+// It checks for errors or an empty buffer and resets the Reader if necessary. If no data is available,
+// it returns io.EOF. Otherwise, it copies the content from the buffer into the payload and updates
+// the read offset.
+//
+// Parameters:
+//   - payload: A byte slice where the data will be copied.
+//
+// Returns:
+//   - n: The number of bytes copied into the payload.
+//   - err: An error if any issues occurred during the read operation or io.EOF if the buffer is empty.
 func (r *Reader) Read(payload []byte) (n int, err error) {
 	if r.err != nil {
 		return 0, r.err
@@ -37,12 +59,20 @@ func (r *Reader) Read(payload []byte) (n int, err error) {
 	return n, err
 }
 
-// Reset resets the Reader buffer to be empty, but it retains the underlying storage
-// for use by future writes.
+// Reset resets the Reader buffer to be empty, but it retains the underlying storage for future use.
+//
+// This function clears the Reader's buffer by setting its length to 0 and resets the read offset
+// to the beginning. The underlying storage is retained, allowing future writes to reuse the buffer.
 func (r *Reader) Reset() {
 	r.buffer = r.buffer[:0]
 	r.offset = 0
 }
 
 // empty reports whether the unread portion of the Reader buffer is empty.
+//
+// This function checks if the unread portion of the Reader's buffer is empty by comparing
+// the length of the buffer to the current read offset.
+//
+// Returns:
+//   - true if the unread portion is empty, false otherwise.
 func (r *Reader) empty() bool { return len(r.buffer) <= r.offset }