Debian Golang如何编写文档 - 问答

Debian 环境下编写 Go 文档的实用指南

一注释与规范

使用 Go 的标准注释：优先用**// 单行注释**，在**// 后加一个空格**；块注释 / / 不用于导出元素的文档，且不支持嵌套。
包级文档：在包声明前使用连续的 // 注释，通常以**Package <包名>**开头，概述用途、示例与注意事项。
导出元素（首字母大写的函数、类型、变量、常量）必须写注释，且注释通常以被注释对象名开头，便于工具提取与阅读。
函数注释建议包含：功能概述、参数含义、返回值/错误条件，必要时给出使用示例或注意事项。
结构体字段可在字段右侧用单行注释说明关键字段语义。
以上规范可直接被 godoc / go doc 提取为文档，是 Go 社区的事实标准。

二本地查看与生成文档

安装文档工具（Debian 上建议用最新版工具链）：
- 安装/更新：sudo apt update && sudo apt install golang -y
- 安装 godoc：go install golang.org/x/tools/cmd/godoc@latest
命令行快速查看：
- 查看包文档：go doc 包名（如：go doc mathutil）
- 查看函数文档：go doc 包名.函数名（如：go doc mathutil.Add）
启动本地文档站点：
- godoc -http=:6060，浏览器访问 http://localhost:6060 浏览项目文档（包含包列表、函数、类型、示例等，支持搜索与跳转）。

三示例包与函数的可提取文档

// Package mathutil 提供基础数学运算工具。
package mathutil

// Add 返回两个整数的和。
// 参数 a 为第一个加数；b 为第二个加数。
// 返回 a 与 b 的和。
func Add(a, b int) int {
    return a + b
}

// Divide 返回 a 除以 b 的商。
// 若 b 为 0，返回 0 与错误。
func Divide(a, b float64) (float64, error) {
    if b == 0 {
        return 0, fmt.Errorf("division by zero")
    }
    return a / b, nil
}

使用方式：
- 命令行：go doc mathutil.Add
- 浏览器：启动 godoc -http=:6060 后查看 /pkg/包路径/ 页面。

四自动化与 API 文档方案

将文档检查纳入 CI：在 CI 中运行 go doc 或静态检查（如 golangci-lint 配合文档规则）以发现未注释的导出元素、格式问题，保证文档与代码同步更新。
API 文档（HTTP 服务）：在 Debian 上可用 Swagger 生态为 Go Web 项目生成在线 API 文档。
- 基于注释生成：使用 swag（如 swag init），在 handler 上添加注释，生成 swagger.json 并通过 Swagger UI 查看（常见访问地址如 http://localhost:端口/swagger/index.html）。
- 基于代码生成：使用 go-swagger（go install github.com/go-swagger/go-swagger/cmd/swagger@latest），从代码/注释生成 swagger.yaml 并启动 UI 服务。
  这两种方式适合在 Gin/Echo 等框架中快速提供交互式 API 文档。

0 赞

0 踩