Documentation Standards Skill
Go documentation conventions following godoc standards.
When to Use
Use when writing or reviewing code documentation.
Package Documentation
go
// Package user provides user management functionality.
//
// This package handles user authentication, authorization,
// and profile management. It supports multiple authentication
// providers and role-based access control.
//
// Example usage:
//
// svc := user.NewService(db)
// user, err := svc.GetUser(ctx, userID)
// if err != nil {
// // handle error
// }
//
package user
Function Documentation
go
// GetUser retrieves a user by ID.
//
// It returns an error if the user is not found or if
// the database connection fails.
//
// Example:
//
// user, err := GetUser(ctx, 1)
// if errors.Is(err, ErrNotFound) {
// // handle not found
// }
//
func GetUser(ctx context.Context, id int) (*User, error) {
// implementation
}
Type Documentation
go
// User represents a system user with authentication details.
type User struct {
// ID is the unique identifier for the user.
ID int
// Name is the user's display name.
Name string
// Email is the user's email address.
// It must be unique across all users.
Email string
}
Example Functions
go
// ExampleGetUser demonstrates how to retrieve a user.
func ExampleGetUser() {
svc := NewService(db)
user, err := svc.GetUser(context.Background(), 1)
if err != nil {
log.Fatal(err)
}
fmt.Println(user.Name)
// Output: John Doe
}
godoc Conventions
- •Start with symbol name - "GetUser retrieves..."
- •Complete sentences - Proper grammar and punctuation
- •No empty lines - Between comment and declaration
- •Explain behavior - What it does, not how
- •Document errors - What errors can be returned
- •Provide examples - For non-obvious usage
README.md Structure
markdown
# Project Name
Brief description.
## Installation
\`\`\`bash
go get github.com/user/project
\`\`\`
## Usage
\`\`\`go
package main
import "github.com/user/project"
func main() {
// example code
}
\`\`\`
## Features
- Feature 1
- Feature 2
## Building
\`\`\`bash
make build
\`\`\`
## Testing
\`\`\`bash
make test
\`\`\`
## License
MIT
Best Practices
- •Document all exports - Public functions, types, constants
- •Be concise - Clear but brief
- •Use examples - For complex APIs
- •Keep updated - Sync with code changes
- •Format correctly - Follow godoc conventions
- •Link related items - Reference related functions
- •Explain non-obvious - Document "why", not "what"