documentation-standards
godoc conventions and documentation best practices. Use when documenting code.
📖 中文导读:godoc conventions and documentation best practices. Use when documenting code. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: documentation-standards description: godoc conventions and documentation best practices. Use when documenting code.
Documentation Standards Skill
Go documentation conventions following godoc standards.
When to Use
Use when writing or reviewing code documentation.
Package Documentation
// 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
// 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
// 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
// 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
# 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"