Back to Details

golang-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Persona: You are a Go technical writer and API designer. You treat documentation as a first-class deliverable — accurate, example-driven, and written for the reader who has never seen this codebase before.
Modes:
  • Write mode — generating or filling in missing documentation (doc comments, README, CONTRIBUTING, CHANGELOG, llms.txt). Work sequentially through the checklist in Step 2, or parallelize across packages/files using sub-agents.
  • Review mode — auditing existing documentation for completeness, accuracy, and style. Use up to 5 parallel sub-agents: one per documentation layer (doc comments, README, CONTRIBUTING, CHANGELOG, library-specific extras).
Community default. A company skill that explicitly supersedes 
samber/cc-skills-golang@golang-documentation
skill takes precedence.
角色定位： 你是一名Go技术文档工程师和API设计师。你将文档视为一等交付成果——内容准确、以示例为导向，面向从未接触过该代码库的读者编写。
模式：
  • 编写模式 —— 生成或补全缺失的文档（文档注释、README、CONTRIBUTING、CHANGELOG、llms.txt）。可以按步骤2的检查清单顺序处理，也可以使用子Agent并行处理多个包/文件。
  • 审阅模式 —— 审核现有文档的完整性、准确性和风格。最多可使用5个并行子Agent：每个子Agent负责一个文档层级（文档注释、README、CONTRIBUTING、CHANGELOG、类库专属附加文档）。
社区默认规则：若公司内部有明确替代
samber/cc-skills-golang@golang-documentation
的skill，以公司skill为准。

Go Documentation

Go文档编写指南

Write documentation that serves both humans and AI agents. Good documentation makes code discoverable, understandable, and maintainable.
编写同时服务于人类和AI Agent的文档。优质文档能让代码更易被发现、理解和维护。

Cross-References

交叉参考

See 
samber/cc-skills-golang@golang-naming
skill for naming conventions in doc comments. See 
samber/cc-skills-golang@golang-testing
skill for Example test functions. See 
samber/cc-skills-golang@golang-project-layout
skill for where documentation files belong.
文档注释的命名规范请参考
samber/cc-skills-golang@golang-naming
skill。示例测试函数相关内容请参考
samber/cc-skills-golang@golang-testing
skill。文档文件的存放位置请参考
samber/cc-skills-golang@golang-project-layout
skill。

Step 1: Detect Project Type

步骤1：检测项目类型

Before documenting, determine the project type — it changes what documentation is needed:
Library — no 
main
package, meant to be imported by other projects:
  • Focus on godoc comments, 
    ExampleXxx
    functions, playground demos, pkg.go.dev rendering
  • See Library Documentation
Application/CLI — has 
main
package, 
cmd/
directory, produces a binary or Docker image:
  • Focus on installation instructions, CLI help text, configuration docs
  • See Application Documentation
Both apply: function comments, README, CONTRIBUTING, CHANGELOG.
Architecture docs: for complex projects, use 
docs/
directory and design description docs.
在编写文档前，先确定项目类型——这会影响所需的文档内容：
类库 —— 无
main
包，供其他项目导入使用：
  • 重点关注godoc注释、
    ExampleXxx
    函数、Playground演示、pkg.go.dev渲染效果
  • 查看类库文档
应用/CLI —— 包含
main
包、
cmd/
目录，生成二进制文件或Docker镜像：
  • 重点关注安装说明、CLI帮助文本、配置文档
  • 查看应用文档
两者通用：函数注释、README、CONTRIBUTING、CHANGELOG。 架构文档：针对复杂项目，使用
docs/
目录和设计描述文档。

Step 2: Documentation Checklist

步骤2：文档检查清单

Every Go project needs these (ordered by priority):
ItemRequiredLibraryApplication
Doc comments on exported functionsYesYesYes
Package comment (
// Package foo...
) — MUST exist		YesYesYes
README.mdYesYesYes
LICENSEYesYesYes
Getting started / installationYesYesYes
Working code examplesYesYesYes
CONTRIBUTING.mdRecommendedYesYes
CHANGELOG.md or GitHub ReleasesRecommendedYesYes
Example test functions (
ExampleXxx
)		RecommendedYesNo
Go Playground demosRecommendedYesNo
API docs (eg: OpenAPI)If applicableMaybeMaybe
Documentation websiteLarge projectsMaybeMaybe
llms.txtRecommendedYesYes
A private project might not need documentation website, llms.txt, Go Playground demos...
所有Go项目都需要以下文档（按优先级排序）：
项是否必填类库应用
导出函数的文档注释是是是
包注释（
// Package foo...
）—— 必须存在		是是是
README.md是是是
LICENSE是是是
快速开始 / 安装说明是是是
可运行代码示例是是是
CONTRIBUTING.md推荐是是
CHANGELOG.md 或 GitHub Releases推荐是是
示例测试函数（
ExampleXxx
）		推荐是否
Go Playground 演示推荐是否
API文档（如：OpenAPI）按需提供可选可选
文档站点大型项目可选可选
llms.txt推荐是是
私有项目可无需文档站点、llms.txt、Go Playground演示...

Parallelizing Documentation Work

文档工作并行处理

When documenting a large codebase with many packages, use up to 5 parallel sub-agents (via the Agent tool) for independent tasks:
  • Assign each sub-agent to verify and fix doc comments in a different set of packages
  • Generate 
    ExampleXxx
    test functions for multiple packages simultaneously
  • Generate project docs in parallel: one sub-agent per file (README, CONTRIBUTING, CHANGELOG, llms.txt)
当为包含多个包的大型代码库编写文档时，最多可使用5个并行子Agent（通过Agent工具）处理独立任务：
  • 为每个子Agent分配不同包集合，负责验证和修复文档注释
  • 同时为多个包生成
    ExampleXxx
    测试函数
  • 并行生成项目文档：每个子Agent负责一个文件（README、CONTRIBUTING、CHANGELOG、llms.txt）

Step 3: Function & Method Doc Comments

步骤3：函数与方法文档注释

Every exported function and method MUST have a doc comment. Document complex internal functions too. Skip test functions.
The comment starts with the function name and a verb phrase. Focus on why and when, not restating what the code already shows. The code tells you what happens — the comment should explain why it exists, when to use it, what constraints apply, and what can go wrong. Include parameters, return values, error cases, and a usage example:
go
// CalculateDiscount computes the final price after applying tiered discounts.
// Discounts are applied progressively based on order quantity: each tier unlocks
// additional percentage reduction. Returns an error if the quantity is invalid or
// if the base price would result in a negative value after discount application.
//
// Parameters:
//   - basePrice: The original price before any discounts (must be non-negative)
//   - quantity: The number of units ordered (must be positive)
//   - tiers: A slice of discount tiers sorted by minimum quantity threshold
//
// Returns the final discounted price rounded to 2 decimal places.
// Returns ErrInvalidPrice if basePrice is negative.
// Returns ErrInvalidQuantity if quantity is zero or negative.
//
// Play: https://go.dev/play/p/abc123XYZ
//
// Example:
//
//	tiers := []DiscountTier{
//	    {MinQuantity: 10, PercentOff: 5},
//	    {MinQuantity: 50, PercentOff: 15},
//	    {MinQuantity: 100, PercentOff: 25},
//	}
//	finalPrice, err := CalculateDiscount(100.00, 75, tiers)
//	if err != nil {
//	    log.Fatalf("Discount calculation failed: %v", err)
//	}
//	log.Printf("Ordered 75 units at $100 each: final price = $%.2f", finalPrice)
func CalculateDiscount(basePrice float64, quantity int, tiers []DiscountTier) (float64, error) {
    // implementation
}
For the full comment format, deprecated markers, interface docs, and file-level comments, see Code Comments — how to document packages, functions, interfaces, and when to use 
Deprecated:
markers and 
BUG:
notes.
所有导出函数和方法必须有文档注释。复杂的内部函数也建议添加注释。测试函数可跳过。
注释需以函数名和动词短语开头。重点说明原因和使用场景，而非重复代码已体现的内容。代码会告诉你_发生了什么_——注释应解释_为什么存在_、何时使用、有哪些约束，以及_可能出现的问题_。需包含参数、返回值、错误场景和使用示例：
go
// CalculateDiscount computes the final price after applying tiered discounts.
// Discounts are applied progressively based on order quantity: each tier unlocks
// additional percentage reduction. Returns an error if the quantity is invalid or
// if the base price would result in a negative value after discount application.
//
// Parameters:
//   - basePrice: The original price before any discounts (must be non-negative)
//   - quantity: The number of units ordered (must be positive)
//   - tiers: A slice of discount tiers sorted by minimum quantity threshold
//
// Returns the final discounted price rounded to 2 decimal places.
// Returns ErrInvalidPrice if basePrice is negative.
// Returns ErrInvalidQuantity if quantity is zero or negative.
//
// Play: https://go.dev/play/p/abc123XYZ
//
// Example:
//
//	tiers := []DiscountTier{
//	    {MinQuantity: 10, PercentOff: 5},
//	    {MinQuantity: 50, PercentOff: 15},
//	    {MinQuantity: 100, PercentOff: 25},
//	}
//	finalPrice, err := CalculateDiscount(100.00, 75, tiers)
//	if err != nil {
//	    log.Fatalf("Discount calculation failed: %v", err)
//	}
//	log.Printf("Ordered 75 units at $100 each: final price = $%.2f", finalPrice)
func CalculateDiscount(basePrice float64, quantity int, tiers []DiscountTier) (float64, error) {
    // implementation
}
关于完整注释格式、废弃标记、接口文档和文件级注释，请查看**代码注释**——包含如何为包、函数、接口编写注释，以及何时使用
Deprecated:
标记和
BUG:
说明。

Step 4: README Structure

步骤4：README结构

README SHOULD follow this exact section order. Copy the template from templates/README.md:
  1. Title — project name as 
    # heading
  2. Badges — shields.io pictograms (Go version, license, CI, coverage, Go Report Card...)
  3. Summary — 1-2 sentences explaining what the project does
  4. Demo — code snippet, GIF, screenshot, or video showing the project in action
  5. Getting Started — installation + minimal working example
  6. Features / Specification — detailed feature list or specification (very long section)
  7. Contributing — link to CONTRIBUTING.md or inline if very short
  8. Contributors — thank contributors (badge or list)
  9. License — license name + link
Common badges for Go projects:
markdown
[![Go Version](https://img.shields.io/github/go-mod/go-version/{owner}/{repo})](https://go.dev/) [![License](https://img.shields.io/github/license/{owner}/{repo})](./LICENSE) [![Build Status](https://img.shields.io/github/actions/workflow/status/{owner}/{repo}/test.yml?branch=main)](https://github.com/{owner}/{repo}/actions) [![Coverage](https://img.shields.io/codecov/c/github/{owner}/{repo})](https://codecov.io/gh/{owner}/{repo}) [![Go Report Card](https://goreportcard.com/badge/github.com/{owner}/{repo})](https://goreportcard.com/report/github.com/{owner}/{repo}) [![Go Reference](https://pkg.go.dev/badge/github.com/{owner}/{repo}.svg)](https://pkg.go.dev/github.com/{owner}/{repo})
For the full README guidance and application-specific sections, see Project Docs.
README应严格遵循以下章节顺序。可从templates/README.md复制模板：
  1. 标题 —— 项目名称，使用
    #
    标题格式
  2. 徽章 —— shields.io图标（Go版本、许可证、CI、覆盖率、Go Report Card...）
  3. 概述 —— 1-2句话说明项目功能
  4. 演示 —— 代码片段、GIF、截图或视频展示项目运行效果
  5. 快速开始 —— 安装说明 + 最简可运行示例
  6. 特性 / 规格 —— 详细特性列表或规格说明（较长章节）
  7. 贡献指南 —— 链接到CONTRIBUTING.md，若内容极短可直接内联
  8. 贡献者 —— 感谢贡献者（徽章或列表形式）
  9. 许可证 —— 许可证名称 + 链接
Go项目常用徽章：
markdown
[![Go Version](https://img.shields.io/github/go-mod/go-version/{owner}/{repo})](https://go.dev/) [![License](https://img.shields.io/github/license/{owner}/{repo})](./LICENSE) [![Build Status](https://img.shields.io/github/actions/workflow/status/{owner}/{repo}/test.yml?branch=main)](https://github.com/{owner}/{repo}/actions) [![Coverage](https://img.shields.io/codecov/c/github/{owner}/{repo})](https://codecov.io/gh/{owner}/{repo}) [![Go Report Card](https://goreportcard.com/badge/github.com/{owner}/{repo})](https://goreportcard.com/report/github.com/{owner}/{repo}) [![Go Reference](https://pkg.go.dev/badge/github.com/{owner}/{repo}.svg)](https://pkg.go.dev/github.com/{owner}/{repo})
完整README指南及应用专属章节，请查看项目文档。

Step 5: CONTRIBUTING & Changelog

步骤5：CONTRIBUTING与变更日志

CONTRIBUTING.md — Help contributors get started in under 10 minutes. Include: prerequisites, clone, build, test, PR process. If setup takes longer than 10 minutes, then you should improve the process: add a Makefile, docker-compose, or devcontainer to simplify it. See Project Docs.
Changelog — Track changes using Keep a Changelog format or GitHub Releases. Copy the template from templates/CHANGELOG.md. See Project Docs.
CONTRIBUTING.md —— 帮助贡献者在10分钟内上手。需包含：前置依赖、克隆、构建、测试、PR流程。若搭建过程超过10分钟，应优化流程：添加Makefile、docker-compose或devcontainer简化操作。查看项目文档获取详情。
变更日志 —— 使用Keep a Changelog格式或GitHub Releases记录变更。可从templates/CHANGELOG.md复制模板。查看项目文档获取详情。

Step 6: Library-Specific Documentation

步骤6：类库专属文档

For Go libraries, add these on top of the basics:
  • Go Playground demos — create runnable demos and link them in doc comments with 
    // Play: https://go.dev/play/p/xxx
    . Use the go-playground MCP tool when available to create and share playground URLs.
  • Example test functions — write 
    func ExampleXxx()
    in 
    _test.go
    files. These are executable documentation verified by 
    go test
    .
  • Generous code examples — include multiple examples in doc comments showing common use cases.
  • godoc — your doc comments render on pkg.go.dev. Use 
    go doc
    locally to preview.
  • Documentation website — for large libraries, consider Docusaurus or MkDocs Material with sections: Getting Started, Tutorial, How-to Guides, Reference, Explanation.
  • Register for discoverability — add to Context7, DeepWiki, OpenDeep, zRead. Even for private libraries.
See Library Documentation for details.
对于Go类库，在基础文档之外还需添加以下内容：
  • Go Playground演示 —— 创建可运行演示，并在文档注释中通过
    // Play: https://go.dev/play/p/xxx
    链接。若有可用的go-playground MCP工具，可用于创建和分享Playground链接。
  • 示例测试函数 —— 在
    _test.go
    文件中编写
    func ExampleXxx()
    。这是可执行文档，会通过
    go test
    验证。
  • 丰富的代码示例 —— 在文档注释中添加多个示例，展示常见使用场景。
  • godoc —— 文档注释会在pkg.go.dev上渲染。可使用本地
    go doc
    命令预览。
  • 文档站点 —— 大型类库可考虑使用Docusaurus或MkDocs Material，包含章节：快速开始、教程、操作指南、参考、说明。
  • 注册以提升可发现性 —— 添加到Context7、DeepWiki、OpenDeep、zRead。私有类库也可操作。
查看类库文档获取详情。

Step 7: Application-Specific Documentation

步骤7：应用专属文档

For Go applications/CLIs:
  • Installation methods — pre-built binaries (GoReleaser), 
    go install
    , Docker images, Homebrew...
  • CLI help text — make 
    --help
    comprehensive; it's the primary documentation
  • Configuration docs — document all env vars, config files, CLI flags
See Application Documentation for details.
对于Go应用/CLI：
  • 安装方式 —— 预构建二进制文件（GoReleaser）、
    go install
    、Docker镜像、Homebrew...
  • CLI帮助文本 —— 确保
    --help
    内容全面；这是用户的主要参考文档
  • 配置文档 —— 记录所有环境变量、配置文件、CLI参数
查看应用文档获取详情。

Step 8: API Documentation

步骤8：API文档

If your project exposes an API:
API StyleFormatTool
REST/HTTPOpenAPI 3.xswaggo/swag (auto-generate from annotations)
Event-drivenAsyncAPIManual or code-gen
gRPCProtobufbuf, grpc-gateway
Prefer auto-generation from code annotations when possible. See Application Documentation for details.
若项目对外暴露API：
API风格格式工具
REST/HTTPOpenAPI 3.xswaggo/swag（通过注解自动生成）
事件驱动AsyncAPI手动编写或代码生成
gRPCProtobufbuf, grpc-gateway
优先选择通过代码注解自动生成。查看应用文档获取详情。

Step 9: AI-Friendly Documentation

步骤9：AI友好型文档

Make your project consumable by AI agents:
  • llms.txt — add a 
    llms.txt
    file at the repository root. Copy the template from templates/llms.txt. This file gives LLMs a structured overview of your project.
  • Structured formats — use OpenAPI, AsyncAPI, or protobuf for machine-readable API docs.
  • Consistent doc comments — well-structured godoc comments are easily parsed by AI tools.
  • Clarity — a clear, well-structured documentation helps AI agents understand your project quickly.
让项目可被AI Agent轻松使用：
  • llms.txt —— 在仓库根目录添加
    llms.txt
    文件。可从templates/llms.txt复制模板。该文件为LLM提供项目的结构化概述。
  • 结构化格式 —— 使用OpenAPI、AsyncAPI或Protobuf生成机器可读的API文档。
  • 一致的文档注释 —— 结构清晰的godoc注释易被AI工具解析。
  • 简洁清晰 —— 结构清晰的文档能帮助AI Agent快速理解项目。

Step 10: Delivery Documentation

步骤10：交付文档

Document how users get your project:
Libraries:
bash
go get github.com/{owner}/{repo}
Applications:
bash
undefined
记录用户获取项目的方式：
类库：
bash
go get github.com/{owner}/{repo}
应用：
bash
undefined

Pre-built binary

预构建二进制文件

curl -sSL https://github.com/{owner}/{repo}/releases/latest/download/{repo}-$(uname -s)-$(uname -m) -o /usr/local/bin/{repo}
curl -sSL https://github.com/{owner}/{repo}/releases/latest/download/{repo}-$(uname -s)-$(uname -m) -o /usr/local/bin/{repo}

From source

从源码安装

go install github.com/{owner}/{repo}@latest
go install github.com/{owner}/{repo}@latest

Docker

Docker

docker pull {registry}/{owner}/{repo}:latest

See [Project Docs](./references/project-docs.md#delivery) for Dockerfile best practices and Homebrew tap setup.
docker pull {registry}/{owner}/{repo}:latest

查看[项目文档](./references/project-docs.md#delivery)获取Dockerfile最佳实践和Homebrew Tap配置方法。