Improve code documentation and comments for clarity and precision

chat.go

@@ -6,20 +6,27 @@ import (
 	"time"
 )
 
-// Options contains configuration options for Chat
+// Options contains configuration options for Chat sessions.
+// S3 provides storage capabilities for persisting chat sessions.
 type Options struct {
 	S3 S3
 }
 
 // Chat represents a chat session with message history
 type Chat struct {
-	ID          string         `json:"id,omitempty"`
-	Key         string         `json:"key,omitempty"`
-	Messages    []Message      `json:"messages"`
-	Created     time.Time      `json:"created"`
-	LastUpdated time.Time      `json:"last_updated"`
-	Metadata    map[string]any `json:"metadata,omitempty"`
-
+	// ID is the unique identifier for the chat session
+	ID string `json:"id,omitempty"`
+	// Key is the storage key used for persistence
+	Key string `json:"key,omitempty"`
+	// Messages contains the chronological history of chat messages
+	Messages []Message `json:"messages"`
+	// Created is the timestamp when the chat session was created
+	Created time.Time `json:"created"`
+	// LastUpdated is the timestamp of the most recent message or modification
+	LastUpdated time.Time `json:"last_updated"`
+	// Metadata stores arbitrary session-related data
+	Metadata map[string]any `json:"metadata,omitempty"`
+	// Options contains the configuration for these chat sessions
 	Options Options `json:"-"`
 }
 

message.go

@@ -13,7 +13,8 @@ type Message struct {
 	ToolCallID string     `json:"tool_call_id,omitempty"` // For tool responses
 }
 
-// ContentString returns the content of the message if its a simple string (not multipart)
+// ContentString returns the content of the message as a string if the content is a simple string.
+// Returns an empty string if the content is not a string type (e.g., multipart content).
 func (m *Message) ContentString() string {
 	v, _ := m.Content.(string)
 	return v
@@ -29,7 +30,9 @@ type Part struct {
 	} `json:"image_url,omitempty"`
 }
 
-// ContentParts returns the parts of the message content if its multipart content
+// ContentParts returns the parts of a multipart message content (text and images).
+// Returns nil for both parts and error if the content is not multipart.
+// Returns error if the content cannot be properly marshaled/unmarshaled.
 func (m *Message) ContentParts() ([]*Part, error) {
 	d, ok := m.Content.([]any)
 	if !ok {

tools.go

@@ -31,7 +31,9 @@ func (f *Function) ArgumentsMap() (map[string]interface{}, error) {
 	return result, nil
 }
 
-// GetPendingToolCalls returns any tool calls that haven't received a reply message
+// RangePendingToolCalls iterates through messages to find and process tool calls that haven't received a response.
+// It performs two passes: first to identify which tool calls have responses, then to process pending calls.
+// The provided function is called for each pending tool call.
 func (chat *Chat) RangePendingToolCalls(fn func(toolCall *ToolCallSession) error) error {
 	// Create a map to track which tool calls have responses
 	responded := make(map[string]bool)
@@ -61,7 +63,8 @@ func (chat *Chat) RangePendingToolCalls(fn func(toolCall *ToolCallSession) error
 	return nil
 }
 
-// ToolCallSession represents a call to an external tool or function in context of a chat session
+// ToolCallSession represents a tool call within a chat context, managing the lifecycle
+// of a single tool invocation including its execution and response handling.
 type ToolCallSession struct {
 	ToolCall *ToolCall
 	Chat     *Chat