GoLand 项目生成符合开源规范的文档需依托 go doc 提取注释并结合静态站点生成器（如 swag/mkdocs），通过配置 Run Configuration 实现一键生成，确保注释格式正确、入口包完整引用且文档输出目录不纳入 Git。
GoLand 项目里怎么生成符合开源规范的文档
GoLand 本身不内置 Go 官方文档生成工具（如 godoc 或现代替代品 docgen），但能无缝集成主流开源文档方案。关键不是“用 IDE 点几下就出文档”，而是让文档生成流程可复现、可提交、可 CI 验证——这才是开源项目真正需要的“规范”。
go doc + static site generator 是最轻量靠谱的选择
Go 社区广泛采用 go doc 提取注释 + 第三方工具转成静态站，比如 swag（面向 API）、mkdocs-material（通用）或 docu（专为 Go 设计）。GoLand 不直接渲染这些，但它能帮你写对注释、跑通命令、把输出目录纳入版本控制。
-
go doc只读//开头的包级/导出符号注释，且必须紧贴声明上方；空行或/* */注释会被忽略 - API 文档推荐用
swag init -g cmd/openim-api/main.go（以 OpenIM 为例），它依赖// @title等特殊标记，GoLand 能高亮提示但不校验语法 - 生成的
docs/目录建议加入.gitignore，只提交源注释和swag.json或mkdocs.yml配置文件
在 GoLand 里配好文档生成命令，别手动敲终端
每次改完注释都要切到终端敲一遍命令？没必要。GoLand 的 Run Configuration 可以存住常用命令，一键触发生成。
GoLand 2026.1.1
下载
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 点击右上角
Add Configuration→+ → External Tool - Name 填
gen-swag，Program 填swag（确保已go install github.com/swaggo/swag/cmd/swag@latest） - Arguments 填
init -g cmd/openim-api/main.go -o ./docs，Working directory 设为项目根目录 - 勾选
After launch: Show console when stdout/stderr is printed，方便看报错
注意：如果 swag 报 undefined: http.SameSiteLaxMode，说明 Go 版本太低（需 ≥1.19）或依赖未更新，运行 go mod tidy 再试。
注释写法不对，再好的工具也白搭
开源项目文档被吐槽“看不懂”，90% 是因为注释没写对格式。GoLand 不强制你写，但会给你两个关键提示：
- 导出函数/类型名首字母必须大写，否则
go doc根本看不到它 - 包级注释必须写在
package xxx上方，且不能和文件头（如//go:build）挨太近，中间至少隔一行 - API 接口注释里，
// @Param的字段名要和实际 struct tag 一致（比如json:"user_id"就得写user_id，不是UserID）
最容易被忽略的是：文档生成工具只扫描 main 包入口点下的所有依赖包。如果你把 handler 放在 internal/ 下但没被 main.go 引用，swag 就找不到它——不是 bug，是设计如此。
