Go包文档直接从源码注释提取，需在声明前用连续//注释（包注释在package语句正上方），go doc命令查本地文档要求模块初始化且路径正确，pkg.go.dev显示需公开仓库、匹配模块路径及有效tag。
Go 的包文档不是靠额外工具生成的，而是直接从源码注释提取的；go doc 和 godoc（已弃用）或 go doc 命令行工具、VS Code 插件、pkg.go.dev 都依赖同一套注释规则——写对注释，文档自然就有了。
如何写才能被 go doc 正确识别
Go 文档注释必须是紧挨着声明（函数、类型、变量、常量、包）上方的连续单行或多行 // 注释，且不能中间空行。包级注释需放在 package xxx 上方，且是文件中第一个非空非注释块。
- ✅ 正确：包注释在
package main之前，且无空行 - ❌ 错误：注释和
package之间有空行，或用了/* */ - ⚠️ 注意：
go doc不解析函数内部注释，只认声明前的注释块 - ? 推荐用
//开头的多行风格，每行都以//开始，保持格式统一
// Package myutil 提供常用工具函数。
// 支持字符串截断、数字校验等基础操作。
package myutil
<p>// TrimSpaceLeft 移除字符串左侧空白字符。
// 如果 s 为 nil，返回空字符串。
func TrimSpaceLeft(s *string) string { ... }
go doc 命令怎么查本地包文档
go doc 是 Go 自带命令，无需安装额外工具，但要求包在 GOPATH 或模块路径下可导入（即能被 go build 找到）。
- 查当前包：运行
go doc（不带参数） - 查某个包：如
go doc fmt或go doc github.com/user/repo/pkgname - 查包内某个符号：如
go doc fmt.Printf、go doc time.Now - 查当前目录下的自定义包：确保
go.mod存在且包路径合法，然后用完整导入路径查（如go doc myproject/internal/util） - ⚠️ 常见失败原因：
no such package多因模块未初始化（缺go mod init）或路径拼错
为什么 pkg.go.dev 上看不到你的包文档
pkg.go.dev 是自动抓取公开 Git 仓库（GitHub/GitLab/Bitbucket）的 tag 或 latest commit，但前提是：
立即学习“go语言免费学习笔记（深入）”；
- 仓库必须是公开的（私有库不会被抓取）
- 模块路径（
module行）需与 Git 地址一致，例如module github.com/you/project对应 GitHub 仓库https://github.com/you/project - 至少有一个 Git tag（如
v0.1.0）或主分支有可构建的 Go 代码（含go.mod） - 包注释必须符合前述格式，否则抓取后显示为空白或 “No documentation found”
- ? 新提交后，pkg.go.dev 通常几小时到一天内更新，不支持手动触发
要不要用 swag 或 gin-swagger？
不要混淆：这些是为 HTTP API 生成 OpenAPI/Swagger 文档的工具，和 Go 原生包文档无关。它们解析的是 // @Summary 这类特殊注释，不参与 go doc 流程，也不影响 godoc 或 pkg.go.dev 显示。
- 如果你要的是「给开发者看的函数用法」→ 用原生注释 +
go doc - 如果你要的是「给前端或测试人员看的 REST 接口说明」→ 用
swag init等方案 - ⚠️ 混用时注意：别把
// @Param这类 swag 注释当成包文档写在函数上方，会污染go doc输出
真正卡住人的往往不是语法，而是包路径和模块初始化这两个环节——go mod init 没跑，或者 go doc 查的路径和实际 import 路径不一致，文档就永远出不来。
