如何给自定义Golang模块添加详细的文档说明-Golang-PHP中文网

go文档注释必须紧贴声明上方且无空行，包级文档需在doc.go中并含package声明，导出符号注释须大写开头、句号结尾。

如何给自定义golang模块添加详细的文档说明

Go 文档注释必须紧贴函数/类型声明上方

Go 的 godoc 和 VS Code 插件（如 Go extension）只识别紧邻声明前的连续块注释，中间不能有空行或其它语句。写在函数体里、声明后、或者用 // 单行注释起头，都不会被解析为文档。

✅ 正确：

// GetUserByID retrieves a user by ID from the database.
// It returns nil and an error if not found or on DB failure.
func GetUserByID(id int) (*User, error) { ... }

❌ 错误：

func GetUserByID(id int) (*User, error) {
    // This comment won't show up in godoc.
    ...
}

❌ 错误：

/*
 * Multi-line comment with blank line after.
 */
<p>func GetUserByID(id int) (*User, error) { ... }</p>

（空行打断了关联）

包级文档要放在 `doc.go` 里，且必须含 `package` 声明

想让整个模块在 pkg.go.dev 或本地 godoc -http=:6060 中显示简介、使用示例和导出项概览，必须新建一个 doc.go 文件，且第一行必须是 package xxx（与模块名一致），再紧跟注释块。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

文件路径：模块根目录下（即 go.mod 所在目录），文件名必须是 doc.go
注释内容建议包含：模块用途、典型用法、关键导出类型/函数的简要说明
不加 package 声明，godoc 会忽略该文件；命名为 README.go 或 docs.go 也无效

示例：

// Package user provides user management logic.
//
// Example usage:
//
//   u, err := user.GetUserByID(123)
//   if err != nil {
//       log.Fatal(err)
//   }
//   fmt.Println(u.Name)
package user

导出符号的文档要以大写字母开头，避免歧义

Go 要求所有导出（public）标识符的文档首句必须是完整句子，且以大写字母开头、以句号结尾。否则 godoc 会把首句当作摘要提取，但格式错误会导致摘要截断或渲染异常。

✅ 推荐：// NewClient creates a new HTTP client with default timeout and retry.
❌ 常见问题：// newClient creates...（小写开头 → 不被识别为摘要）、// Creates a new HTTP client（缺主语、无句号 → 摘要不完整）
注意：非导出符号（小写开头的函数/字段）即使写了注释，也不会出现在生成文档中
如果函数签名复杂（如带多个返回值），可在注释中用 // Returns: ... 显式说明，但不是必须

运行 `godoc` 本地预览时，工作目录决定可见范围

执行 godoc -http=:6060 后，访问 http://localhost:6060 看到的文档范围取决于你启动命令时所在的目录 —— 它只索引当前目录及其子目录下的 Go 包，不会自动扫描整个 GOPATH 或 module path。

想查看自己模块的文档：cd 到模块根目录（含 go.mod），再运行 godoc -http=:6060
若模块未发布到公网，pkg.go.dev 不会收录；本地 godoc 是唯一快速验证方式
VS Code 中 hover 提示依赖 gopls，它默认读取源码注释，但要求注释格式合规，否则提示为空白或仅显示签名
CI 中可加检查：go list -f '{{.Doc}}' ./... | grep -q '^$' && echo "missing docs"（粗略检测空文档）

文档能被正确解析的前提是结构合规，而不是字数多少。最容易被忽略的是 doc.go 的命名和包声明，以及函数注释与声明之间有没有空行 —— 这两点一错，整个包的文档就“消失”了。