Write API Docs

This skill guides you through creating API reference documentation for Beluga AI packages.

Prerequisites

• Package code to document
• Understanding of package purpose
• Access to test files for usage examples

Steps

1. Analyze Package Structure

Review the package to identify:

## Package Analysis: pkg/[name]

### Public Types
- [ ] `Config` - Configuration struct
- [ ] `Component` - Main type
- [ ] `Interface` - Public interface
- [ ] `Error` - Error type
- [ ] `Option` - Functional option type

### Public Functions
- [ ] `New...()` - Constructor
- [ ] `RegisterGlobal()` - Registry (if applicable)
- [ ] `NewProvider()` - Provider factory (if applicable)

### Public Methods
- [ ] `Component.Method1()`
- [ ] `Component.Method2()`

### Constants/Variables
- [ ] Error codes
- [ ] Default values

2. Document Package Overview

# Package [name]

`import "github.com/lookatitude/beluga-ai/pkg/[name]"`

## Overview

[Brief description of what this package provides]

## Key Features

- [Feature 1]
- [Feature 2]
- [Feature 3]

## Quick Start

```go
package main

import (
    "context"
    "github.com/lookatitude/beluga-ai/pkg/[name]"
)

func main() {
    // Minimal working example
    component := name.NewComponent(
        name.WithTimeout(30 * time.Second),
    )
    result, err := component.Process(context.Background(), input)
    if err != nil {
        // handle error
    }
    // use result
}

Architecture

[Optional: Mermaid diagram showing component relationships]

### 3. Document Types

#### Configuration

```markdown
## Types

### Config

Configuration for creating a [Component].

```go
type Config struct {
    // Name is the identifier for this component.
    // Required.
    Name string `mapstructure:"name" validate:"required"`

    // Timeout is the maximum duration for operations.
    // Default: 30s
    Timeout time.Duration `mapstructure:"timeout" validate:"min=1s"`

    // MaxRetries is the number of retry attempts on transient failures.
    // Default: 3, Range: 0-10
    MaxRetries int `mapstructure:"max_retries" validate:"gte=0,lte=10"`
}

Fields

Example

config := name.Config{
    Name:       "my-component",
    Timeout:    60 * time.Second,
    MaxRetries: 5,
}

#### Main Type

```markdown
### Component

Component is the main type for [purpose].

```go
type Component struct {
    // contains filtered or unexported fields
}

Creating a Component

// Using default configuration
component := name.NewComponent()

// With functional options
component := name.NewComponent(
    name.WithTimeout(60 * time.Second),
    name.WithLogger(logger),
    name.WithMetrics(metrics),
)

// From configuration
component, err := name.NewComponentFromConfig(config)

#### Interface

```markdown
### Interface

Interface defines the contract for [purpose].

```go
type Interface interface {
    // Process performs the main operation.
    // Returns ErrCodeInvalidInput if input is invalid.
    // Returns ErrCodeTimeout if the operation exceeds the configured timeout.
    Process(ctx context.Context, input Input) (Output, error)

    // Close releases resources held by the component.
    Close() error
}

### 4. Document Functions

```markdown
## Functions

### NewComponent

```go
func NewComponent(opts ...Option) *Component

NewComponent creates a new Component with the given options.

Parameters

Returns

Example

component := name.NewComponent(
    name.WithTimeout(30 * time.Second),
    name.WithMaxRetries(5),
)

NewProvider

func NewProvider(ctx context.Context, providerName string, config Config) (Interface, error)

NewProvider creates a new provider instance by name from the global registry.

Parameters

Returns

Errors

• ErrCodeNotFound: Provider name not registered
• ErrCodeInvalidConfig: Configuration validation failed

Example

provider, err := name.NewProvider(ctx, "openai", name.Config{
    Timeout: 30 * time.Second,
})
if err != nil {
    log.Fatalf("Failed to create provider: %v", err)
}

### 5. Document Methods

```markdown
## Methods

### Component.Process

```go
func (c *Component) Process(ctx context.Context, input Input) (Output, error)

Process performs the main operation on the given input.

Parameters

Returns

Errors

Example

result, err := component.Process(ctx, name.Input{
    Value: "test data",
})
if err != nil {
    var e *name.Error
    if errors.As(err, &e) {
        switch e.Code {
        case name.ErrCodeTimeout:
            // Handle timeout
        case name.ErrCodeRateLimit:
            // Handle rate limit
        default:
            // Handle other errors
        }
    }
    return err
}
fmt.Printf("Result: %s\n", result.Value)

### 6. Document Options

```markdown
## Options

### WithTimeout

```go
func WithTimeout(d time.Duration) Option

WithTimeout sets the maximum duration for operations.

Example

component := name.NewComponent(
    name.WithTimeout(60 * time.Second),
)

WithLogger

func WithLogger(l Logger) Option

WithLogger sets the logger for the component.

WithMetrics

func WithMetrics(m *Metrics) Option

WithMetrics sets the OTEL metrics collector.

### 7. Document Errors

```markdown
## Errors

### Error Type

```go
type Error struct {
    Op   string    // Operation that failed
    Err  error     // Underlying error
    Code ErrorCode // Error classification
}

Error Codes

Checking Error Codes

result, err := component.Process(ctx, input)
if err != nil {
    var e *name.Error
    if errors.As(err, &e) {
        if e.Code == name.ErrCodeRateLimit {
            // Implement backoff and retry
        }
    }
    return err
}

### 8. Document Providers (if applicable)

```markdown
## Providers

### Available Providers

| Provider | Description | Import |
|----------|-------------|--------|
| `openai` | OpenAI API | Built-in |
| `anthropic` | Anthropic API | Built-in |
| `ollama` | Local Ollama | Built-in |

### Registering Custom Providers

```go
func init() {
    name.RegisterGlobal("custom", func(ctx context.Context, config name.Config) (name.Interface, error) {
        return NewCustomProvider(config)
    })
}

## Documentation Checklist

- [ ] Package overview with import path
- [ ] Quick start example
- [ ] All public types documented
- [ ] All public functions documented
- [ ] All public methods documented
- [ ] All options documented
- [ ] Error codes with descriptions
- [ ] Providers listed (if applicable)
- [ ] Examples compile and run
- [ ] Links to guides and tutorials

## Output

Complete API reference with:
- Package overview
- Type documentation with fields
- Function signatures with parameters/returns
- Method documentation with errors
- Functional options
- Error handling guide
- Provider documentation
- Working code examples