go-source-documentation

Go Source Documentation Skill

Activation

Activate this skill when the user:

• Asks to document Go source files or test files
• Asks to add doc comments to Go code
• Asks to improve or fix Go documentation
• Mentions /document-go or /doc-go
• Asks to add file headers to Go files
• Asks to document a Go package

Prerequisites

Before starting, gather context:

1. Read the target file(s) completely to understand structure and purpose
2. Read related files in the same package to understand the package API surface
3. Check existing tests to understand what behavior the code implements
4. Identify the package role within the project architecture
5. Use Context7 to verify current Go doc comment conventions if uncertain

Documentation Patterns

Pattern 1: Package Comment

Every package needs exactly one Package comment, typically in the main file or a dedicated doc.go:

// Package tools implements MCP tool handlers for GitLab operations.
//
// Each tool follows a consistent pattern: a typed input struct with jsonschema
// tags defining the parameter schema, a handler function that calls the GitLab
// API, and a typed output struct for the response.
//
// Actions are exposed through [ActionSpecs], which feed catalog-backed meta,
// dynamic, gitlab://tools resources, and individual tool surfaces with
// appropriate annotations.
//
// # Supported Operations
//
//   - Branches: create, list, protect, unprotect
//   - Issues: create, list, get, update, search
//   - Merge Requests: create, list, get, update, merge
//   - Files: get content, create, update
//   - Commits: list, get details
package tools

Pattern 2: File Header Comment

For multi-file packages, each file gets a header describing its scope. The header goes immediately before the package declaration:

// branches.go implements MCP tool handlers for GitLab branch operations.
//
// It provides the following tools:
//   - gitlab_branch_create:     Create a new branch from a ref
//   - gitlab_branch_list:       List branches with optional search
//   - gitlab_branch_protect:    Protect a branch with access levels
//   - gitlab_branch_unprotect:  Remove protection from a branch
package tools