chore: Improve documentation in source files

Author: unfunco

.gitattributes

@@ -0,0 +1,2 @@
+.editorconfig export-ignore
+.github/ export-ignore

.github/workflows/ci.yaml

@@ -32,6 +32,8 @@ jobs:
   release:
     name: Release?
     needs: [ verify ]
+    outputs:
+      version: ${{ steps.release.outputs.version }}
     permissions:
       contents: write
       pull-requests: write
@@ -46,3 +48,14 @@ jobs:
         config-file: .github/release-config.json
         manifest-file: .github/release-manifest.json
         token: ${{ secrets.GITHUB_TOKEN }}
+
+  configure_version:
+    name: Configure version
+    if: ${{ steps.release.outputs.version }}
+    needs: [ release ]
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+    - run: |
+        sed 's/^[^0-9]*(([0-9]+\.)*[0-9]+).*/\1/p'

README.md

@@ -1,5 +1,8 @@
 # Anthropic SDK for Go
 
+> [!NOTE]  
+> This is not an official SDK and I have no affiliation with [Anthropic].
+
 Client library for interacting with the [Anthropic] safety-first language model
 REST APIs.
 

anthropic.go

@@ -37,6 +37,7 @@ func NewClient(client *http.Client) *Client {
 	claude := &Client{client: client}
 	claude.baseURL, _ = url.Parse(defaultBaseURL)
 	claude.reusable.client = claude
+
 	claude.Messages = (*MessagesService)(&claude.reusable)
 
 	return claude

messages.go

@@ -13,39 +13,13 @@ type Message struct {
 	Role    string `json:"role"`
 }
 
-// Usage defines billing and rate-limit usage information.
-// Billing and rate-limiting are driven by token counts, since tokens represent
-// the underlying cost to Anthropic.
-type Usage struct {
-	InputTokens  int `json:"input_tokens"`
-	OutputTokens int `json:"output_tokens"`
-}
-
 type Content struct {
 	Type string `json:"type"`
 	Text string `json:"text"`
 }
 
 // CreateMessageInput defines a structured list of input messages.
 type CreateMessageInput struct {
-	// MaxTokens defines the maximum number of tokens to generate before
-	// stopping. Token generation may stop before reaching this limit, this only
-	// specifies the absolute maximum number of tokens to generate. Different
-	// models have different maximum token limits.
-	MaxTokens int `json:"max_tokens"`
-	// Messages are the input messages, models are trained to operate on
-	// alternating user and assistant conversational turns. When creating a new
-	// message, prior conversational turns can be specified with this field.
-	Messages []Message `json:"messages"`
-	// Model defines the language model that will be used to complete the
-	// prompt. See model.go for a list of available models.
-	Model LanguageModel `json:"model"`
-	// StopSequences defines custom text sequences that will cause the model to
-	// stop generating.
-	StopSequences []string `json:"stop_sequences,omitempty"`
-	// System provides a means of specifying context and instructions to the
-	// model, such as specifying a particular goal or role.
-	System string `json:"system,omitempty"`
 	// Temperature defines the amount of randomness injected into the response.
 	// Note that even with a temperature of 0.0, results will not be fully
 	// deterministic.
@@ -54,23 +28,45 @@ type CreateMessageInput struct {
 	// Recommended for advanced use cases only. You usually only need to use
 	// Temperature.
 	TopK *int `json:"top_k,omitempty"`
-	// TopP (nucleus-sampling) defines the cumulative probability of the highest probability.
+	// TopP (nucleus-sampling) defines the cumulative probability of the highest
+	// probability.
 	// Recommended for advanced use cases only. You usually only need to use
 	// Temperature.
 	TopP *float64 `json:"top_p,omitempty"`
+	// Model defines the language model that will be used to complete the
+	// prompt. See model.go for a list of available models.
+	Model LanguageModel `json:"model"`
+	// System provides a means of specifying context and instructions to the
+	// model, such as specifying a particular goal or role.
+	System string `json:"system,omitempty"`
+	// Messages are the input messages, models are trained to operate on
+	// alternating user and assistant conversational turns. When creating a new
+	// message, prior conversational turns can be specified with this field.
+	Messages []Message `json:"messages"`
+	// StopSequences defines custom text sequences that will cause the model to
+	// stop generating.
+	StopSequences []string `json:"stop_sequences,omitempty"`
+	// MaxTokens defines the maximum number of tokens to generate before
+	// stopping. Token generation may stop before reaching this limit, this only
+	// specifies the absolute maximum number of tokens to generate. Different
+	// models have different maximum token limits.
+	MaxTokens int `json:"max_tokens"`
 }
 
+// CreateMessageOutput defines the response from creating a new message.
 type CreateMessageOutput struct {
-	Id           *string    `json:"id"`
-	Type         *string    `json:"type"`
-	Role         *string    `json:"role"`
-	Model        *string    `json:"model"`
-	StopSequence *string    `json:"stop_sequence"`
-	StopReason   *string    `json:"stop_reason"`
-	Content      []*Content `json:"content"`
-	Usage        *Usage     `json:"usage"`
+	ID           *string `json:"id"`
+	Type         *string `json:"type"`
+	Role         *string `json:"role"`
+	Model        *string `json:"model"`
+	StopSequence *string `json:"stop_sequence"`
+	StopReason   *string `json:"stop_reason"`
+	Usage        *Usage  `json:"usage"`
+	// Content is a list of generated messages.
+	Content []*Content `json:"content"`
 }
 
+// String implements the fmt.Stringer interface for CreateMessageOutput.
 func (c *CreateMessageOutput) String() string {
 	return c.Content[0].Text
 }

transport.go

@@ -11,13 +11,18 @@ type Transport struct {
 	APIKey string
 }
 
+// Client returns an HTTP client that will include the API key in the request,
+// and is safe for concurrent use by multiple goroutines.
 func (t *Transport) Client() *http.Client {
 	return &http.Client{
 		Transport: t,
 	}
 }
 
 // RoundTrip implements the http.RoundTripper interface.
+// It makes a copy of the HTTP request so that it complies with the requirements
+// of the interface and adds the API key to the request before calling the
+// underlying default http.RoundTripper.
 func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error) {
 	if t.APIKey == "" {
 		return nil, errors.New("API key is required")

usage.go

@@ -0,0 +1,16 @@
+package anthropic
+
+import "fmt"
+
+// Usage defines billing and rate-limit usage information.
+// Billing and rate-limiting are driven by token counts, since tokens represent
+// the underlying cost to Anthropic.
+type Usage struct {
+	InputTokens  int `json:"input_tokens"`
+	OutputTokens int `json:"output_tokens"`
+}
+
+// String implements the fmt.Stringer interface for Usage.
+func (u *Usage) String() string {
+	return fmt.Sprintf("Input: %d, Output: %d", u.InputTokens, u.OutputTokens)
+}

usage_test.go

@@ -0,0 +1,39 @@
+package anthropic
+
+import "testing"
+
+func TestUsage_String(t *testing.T) {
+	tests := []struct {
+		name  string
+		usage *Usage
+		want  string
+	}{
+		{
+			name:  "empty",
+			usage: &Usage{},
+			want:  "Input: 0, Output: 0",
+		},
+		{
+			name:  "input",
+			usage: &Usage{InputTokens: 1},
+			want:  "Input: 1, Output: 0",
+		},
+		{
+			name:  "output",
+			usage: &Usage{OutputTokens: 2},
+			want:  "Input: 0, Output: 2",
+		},
+		{
+			name:  "both",
+			usage: &Usage{InputTokens: 3, OutputTokens: 4},
+			want:  "Input: 3, Output: 4",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.usage.String(); got != tt.want {
+				t.Errorf("Usage.String() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}