dennisonbertram Documentation Generation
You are now operating in documentation generation mode.
Go Documentation (godoc)
Viewing Package Documentation
# View package documentation in terminal
go doc ./internal/harness
# View a specific type
go doc ./internal/harness Runner
# View a specific method
go doc ./internal/harness Runner.Run
# View all exported symbols
go doc -all ./internal/harness
# View unexported symbols too
go doc -u ./internal/harness
# View documentation for a standard library package
go doc net/http
go doc net/http.Server
Serving Documentation Locally
# Install pkgsite (modern godoc server)
go install golang.org/x/pkgsite/cmd/pkgsite@latest
# Serve docs for the current module
pkgsite -open .
# Or use the classic godoc server
go install golang.org/x/tools/cmd/godoc@latest
godoc -http=:6060
# Open http://localhost:6060/pkg/go-agent-harness/
Writing Good godoc Comments
// Package harness implements the agent execution loop.
// It coordinates LLM calls, tool dispatch, and step management.
package harness
// Runner executes an agent conversation loop.
// It drives the LLM → tool call → execute → repeat cycle
// until the step limit is reached or the agent signals completion.
type Runner struct {
// unexported fields
}
// Run executes the agent loop for the given conversation.
// It returns an error if the context is cancelled, the step limit
// is exceeded, or a tool call fails fatally.
//
// Run is safe for concurrent use.
func (r *Runner) Run(ctx context.Context, conv *Conversation) error {
// implementation
}
Documentation Linting
# Check for doc format issues
go vet ./...
# Install and run staticcheck (catches missing docs on exported symbols)
go install honnef.co/go/tools/cmd/staticcheck@latest
staticcheck ./...
# Install golangci-lint with godot linter (doc comments end with period)
golangci-lint run --enable godot ./...
OpenAPI / Swagger Documentation (swaggo)
Installation
go install github.com/swaggo/swag/cmd/swag@latest
Annotate Handlers
// @Summary List users
// @Description Get a paginated list of all users
// @Tags users
// @Accept json
// @Produce json
// @Param page query int false "Page number (default: 1)"
// @Param limit query int false "Page size (default: 20)"
// @Success 200 {object} ListUsersResponse
// @Failure 401 {object} ErrorResponse
// @Failure 500 {object} ErrorResponse
// @Router /api/v1/users [get]
func (s *Server) handleListUsers(w http.ResponseWriter, r *http.Request) {
// implementation
}
Generate OpenAPI Spec
# Generate docs/ directory with swagger.json and swagger.yaml
swag init -g cmd/harnessd/main.go
# Specify output directory
swag init -g cmd/harnessd/main.go -o api/docs
# Format swag annotations
swag fmt
Serve Swagger UI
import (
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
_ "go-agent-harness/api/docs" // generated docs
)
// Register Swagger UI route
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
// Open http://localhost:8080/swagger/index.html
README Generation Patterns
Package README Skeleton
# package-name
Brief one-sentence description.
## Overview
What problem this package solves and when to use it.
## Installation
```bash
go get go-agent-harness/internal/package-name
Usage
// Minimal working example
API Reference
See godoc for full API docs.
Contributing
Run tests: go test ./...
### Auto-generate Changelog Entry
```bash
# Generate changelog from git log since last tag
LAST_TAG=$(git describe --tags --abbrev=0)
git log ${LAST_TAG}..HEAD --pretty=format:"- %s (%h)" --no-merges
Documentation Checklist
Before merging a new package or significant API change:
# 1. All exported symbols have doc comments
grep -n '^func \|^type \|^var \|^const ' *.go | grep -v '//'
# 2. Run go vet to catch basic issues
go vet ./...
# 3. View rendered docs
go doc -all ./...
# 4. Check for TODO/FIXME left in exported symbols
grep -rn 'TODO\|FIXME' --include='*.go' .
# 5. Verify examples compile
go test -run=Example ./...