SuperAPI AI 工具集

go-documentation

写作与研究

查看项目

更新于 10-15 21:37

技能介绍

用途:为 Go 代码编写符合工具链约定的文档,使注释在 pkg.go.dev 上渲染为可浏览的文档,而非噪音。

主要能力:1) 文档注释形式:每个导出标识符都要有以自身名称开头的完整句子注释,说明行为、错误条件、nil/零值处理与并发安全性;相关常量或变量组可共用一条块注释。2) 包文档:每个包一条包注释,写在 package 子句上,以“Package ... ”开头;内容较长时放入专门的 doc.go;main 包的注释描述命令及其标志。3) 文档链接与格式(Go 1.19+):用 [Name]、[Type.Method]、[pkg/path] 生成超链接,行首 # 为标题,缩进行渲染为代码块。4) 可测试 Example:放在 example_test.go 的 <pkg>_test 包中,命名如 ExampleParseDuration、ExamplePolicy_Do,带 // Output: 注释才会被 go test 执行校验。5) 弃用:段落以 Deprecated: 开头并指明替代项。6) 明确不应写的内容:复述签名、维护历史、注释掉的死代码。

使用方式:按上述约定编写注释与 Example,然后用 go vet ./...、gofmt -l .、go test ./...、go doc ./mypkg Symbol 验证;如需可浏览预览,可运行 go run golang.org/x/pkgsite/cmd/pkgsite@latest 并打开模块。

适用场景:为 Go 库或命令补充文档、审查文档质量、准备发布到 pkg.go.dev。

限制:资料未提供该技能的安装方式、依赖要求、收费与平台支持信息;文档链接与 gofmt 规范化注释需 Go 1.19+。