go注释的标准语言|全面解析Go语言注释规范
在Go语言开发中,注释不仅是代码可读性的基石,更是团队协作、项目维护、自动化文档生成乃至CI/CD流程集成的核心环节。Go语言对注释的处理既遵循通用编程语言的逻辑,又具备自身独特的语义约束与工具链支持。本页面系统梳理Go注释的**标准语言**规范、语法细节、类型划分、文档机制、配套工具、行业最佳实践及高频问题,为开发者提供一份权威、详实、可直接落地的注释指南。
Go语言的注释设计哲学强调简洁性与一致性:单行注释(//)用于简短说明或临时禁用代码;多行注释()适用于临时块注释或复杂结构说明;而文档注释(即以注释块紧接声明语句前的注释)则是godoc等工具生成API文档的唯一来源。三者虽形式各异,却共享同一套注释语义规则:**不允许嵌套**(即多行注释内不能再写)、**不支持行尾注释混用多行注释起始符**、**注释内容不参与编译**,且**所有注释均不计入Go程序的语法树**(AST)——这意味着注释不会影响程序行为,但其位置与内容直接影响开发体验与自动化流程。
值得注意的是,Go语言**未定义正式的“文档注释”关键字或标签**(如Java的@deprecated或Python的docstring关键字),而是通过**位置约定与格式规范**实现文档化:当一个注释块(无论是单行还是多行)紧接在函数、类型、常量、变量等声明语句之前、且与声明之间无空行或注释分隔时,该注释即被视为文档注释。例如:
package main
// Max returns the larger of two integers.
func Max(a, b int) int {
if a > b {
return a
}
return b
}
此处的“Max returns the larger of two integers.”即构成文档注释,可被godoc提取并展示为函数说明。此机制虽无显式标记,却通过语言工具链深度集成,成为Go生态系统中事实上的**标准语言注释模式**。
Go社区普遍遵循《Effective Go》与《Go Code Review Comments》中确立的注释规范:文档注释首句应为**简洁概括性陈述**(通常以被注释项名称开头),后续可补充参数、返回值、错误处理、并发安全等细节;避免冗余描述(如“This function returns...”);使用主动语态、现在时态;参数说明统一采用“paramName ...”格式。这些规范虽非编译器强制要求,但已成为Go开源项目事实上的**行业共识**,违反者往往在PR审核中被要求修正。
此外,Go注释在版本控制中具有特殊价值:Git diff中注释变更会清晰展示逻辑演进脉络,而注释中的TODO/FIXME/HACK等标记词可被grep或IDE高亮识别,辅助开发任务追踪。因此,合理注释不仅是技术需求,更是工程管理工具。本页将从语法、类型、工具、实践等多维度展开,确保读者掌握从基础到进阶的**go注释的标准语言**全貌。
一、Go注释基础语法与底层规则
Go语言注释语法极其简洁,仅包含两种形式:单行注释(//)与多行注释()。其核心规则由Go语言规范(The Go Programming Language Specification)明确定义,所有编译器实现(如gc、gccgo)必须严格遵守。以下为关键语法要点:
- 单行注释:以“//”开头,延伸至当前行末尾。可独立成行,也可置于代码行尾(行尾注释),但行尾注释与代码之间至少需一个空格分隔。
- 多行注释:以“”结束,可跨越任意行数。**禁止嵌套**,即“ outer”中内层“*/”将提前结束注释,导致语法错误。
- 注释内容中可包含任意Unicode字符(包括中文、emoji等),但编译器仅将其视为字节序列,不做语义解析。
- 注释不能出现在词法单元(token)内部。例如“fmt.Println(“Hello”)”中,若写成“fmt.Pri//ntln”将导致编译错误——“//ntln”被视作独立token,破坏语法结构。
以下为**合规与违规示例对比**:
| 类型 | 示例代码 | 说明 |
|---|---|---|
| 合规单行 | // 这是有效注释 | 独立成行注释 |
| 合规行尾 | x := 1 // 初始化x | 代码后跟至少一个空格 |
| 合规多行 | | 可跨多行 |
| 合规文档 | // 文档注释 | 紧接声明前无空行 |
| 违规嵌套 | */ | 内层“*/”提前结束 |
| 违规断词 | fmt.Pri//ntln("Hi") | 注释切分标识符 |
| 违规行尾无空格 | x := 1//error | 行尾注释前需空格 |
特别说明:行尾注释虽语法合法,但Go社区普遍建议**仅在简短说明时使用**(如“// error handling”),复杂逻辑应另起一行注释。原因在于:行尾注释易导致代码行过长(影响可读性),且在重构时易与代码分离,降低维护性。Go官方工具链(如gofmt)在格式化时会自动调整行尾注释位置,例如:
// 原始代码
func foo() { x := 1 // 初始化变量 }
// gofmt处理后
func foo() {
x := 1 // 初始化变量
}
此行为确保注释与关联代码保持视觉关联,是**go注释的标准语言**工程化实践之一。开发者应避免手动控制行尾注释位置,交由工具统一处理。
多行注释的常见误用场景是临时禁用大段代码(“注释掉代码”)。虽然技术上可行,但Go社区强烈反对此做法——应使用条件编译(// +build)或专用调试包(如log/slog)替代。原因有三:其一,多行注释内含的“”若被意外删除会导致语法错误;其二,被注释代码仍参与词法分析,增加编译负担;其三,版本控制中注释块易产生冗余diff。推荐做法是使用IDE的“Comment Code”功能(通常调用gofmt -w),其会自动将代码转为单行注释,且保留原始结构便于恢复。
注释中的特殊字符需转义处理:例如“// 包含“转义字符””是合法的,因引号未被解析为字符串定界符;但“// 路径C:\Users”需写为“// 路径C:\\Users”,否则“\U”会被误认为Unicode转义序列起始。此细节常被忽视,却在Windows路径处理中高频触发编译错误,是**go注释的标准语言**易错点之一。
二、Go注释三大类型详解与适用场景
Go语言注释虽仅两种语法形式,但按功能与用途可划分为三大类型:**单行注释(Line Comment)**、**多行注释(Block Comment)**、**文档注释(Doc Comment)**。三者在语义上无本质差异,但因使用场景、工具支持、社区规范不同,需严格区分。下表为类型对比:
| 类型 | 语法 | 典型用途 | 工具支持 | 社区规范 |
|---|---|---|---|---|
| 单行注释 | // content | 行内说明、临时禁用代码、TODO标记 | 所有IDE支持高亮、搜索 | 首字母大写,句末可不加句号 |
| 多行注释 | 复杂逻辑说明、大段代码块注释、临时禁用 | 仅基础IDE支持折叠 | 避免嵌套,慎用于禁用代码 | |
| 文档注释 | // 或 紧接声明前 | 生成API文档、IDE提示、godoc展示 | godoc、go doc、IDE自动提取 | 首句为摘要,独立成段 |
以下分述每种类型细节:
2.1 单行注释(Line Comment)
单行注释是Go开发中最高频使用的注释形式,占比超80%。其优势在于简洁、安全、易集成:不会破坏词法结构,且可与代码同处一行。典型用法包括:
- 解释变量/常量含义:
maxRetries := 3 // 最大重试次数 - 标注逻辑分支原因:
if err != nil { return err } // 非零错误码直接返回 - 标记待办任务:
// TODO: 支持超时参数 - 禁用单行代码:
// fmt.Println("debug")
规范要求:文档注释(即用于生成API文档的注释)必须使用单行注释形式,且**首句需为完整句子**,以被注释项名称开头。例如:
// Config represents application configuration.
type Config struct {
Timeout time.Duration
Retries int
}
此处“Config represents application configuration.”即文档注释首句,后续可接参数说明、字段解释等。godoc会将首句作为摘要显示在索引页,后续内容在详情页展开。若首句非完整句子(如“Represents...”),工具可能无法正确解析摘要,导致文档展示混乱——这是Go社区严格遵守的**go注释的标准语言**原则。
单行注释中可嵌入特殊标记词(Tag),用于工具识别:
- TODO:待办任务,格式如“// TODO(username): 描述”
- FIXME:已知缺陷,需修复
- HACK:临时方案,非长久之计
- NOTE:重要提示,常用于并发安全说明
这些标记可被IDE高亮显示(如VS Code的Todo Tree插件),或通过grep统计任务量。例如在项目根目录执行“grep -r TODO”即可获取所有待办事项列表。但需注意:标记词需**大写**且**独立成词**(如“// todo: fix”无效),否则不被识别。
2.2 多行注释(Block Comment)
多行注释适用于跨行说明,但使用频率远低于单行注释。主要场景有:
- 复杂算法逻辑分段注释:
func fib(n int) int { if n < 2 { return n } return fib(n-1) + fib(n-2) } - 文件头版权说明(非必须,但部分企业项目要求):
package main
- 临时禁用多行代码块(不推荐)
多行注释的常见陷阱是误用缩进符号(如“*”或“#”)。Go语言**不支持**类似Java的Javadoc风格(即“”),多行注释内缩进仅为视觉辅助,工具不解析其语义。例如:
func Max(a, b int) int { ... }
此写法中“参数:a - 整数”不会被godoc识别为参数说明,仅作为普通文本。正确做法是使用文档注释格式:// Max returns the larger of two integers.后接参数描述,或直接在函数体注释中用“@param”等标记——但后者**不被Go官方工具支持**,属第三方扩展(如goreadme插件),违反Go社区规范。
多行注释**禁止嵌套**的底层原因在于词法分析器设计:Go编译器使用状态机扫描注释,遇到“”时退出。若允许嵌套,需引入栈结构管理状态,违背Go语言“简单即美”的哲学。因此,以下代码必然报错:
// 此处“*/”结束outer invalid code */
编译器会报错:invalid character 'c' in comment(因“invalid code”被误认为代码)。开发者需手动调整注释结构,或改用单行注释分段说明。
2.3 文档注释(Doc Comment)
文档注释是Go注释体系的核心,直接关联API文档生成与IDE智能提示。其本质是**位置敏感型注释**:当注释块与声明语句之间无空行、无其他注释、无空白符时,即被工具识别为文档注释。例如:
// 文档注释(紧接声明)
func Foo() {}
func Bar() {}
二者均可被godoc提取。但若中间插入空行或注释,则失效:
// 无效:中间有空行
func Foo() {}
// 无效:中间有其他注释
// 说明性文字
func Bar() {}
文档注释的格式规范由《Go Code Review Comments》定义,关键点如下:
- 首句为**单句摘要**,以被注释项名称开头(如“Max returns...”、“Config represents...”),长度≤79字符。
- 后续段落用空行分隔,解释参数、返回值、错误、并发安全等。
- 参数说明格式:“paramName ...”,如“ctx is used for cancellation.”。
- 返回值说明格式:“Returns ...”,如“Returns the larger value, or an error if invalid.”。
- 避免冗余:不重复函数签名(如“This function takes two integers”),因读者可直接查看签名。
完整示例:
// Max returns the larger of two integers.
//
// If both values are equal, it returns that value.
// It handles negative numbers correctly.
func Max(a, b int) int {
if a > b {
return a
}
return b
}
godoc处理后显示:
func Max(a, b int) int
Max returns the larger of two integers.
If both values are equal, it returns that value. It handles negative numbers correctly.
此规范确保文档结构统一,极大提升开源项目可读性。违反者(如首句未以名称开头)在提交PR时会被CI工具(如golint)警告,要求修正。因此,遵循**go注释的标准语言**文档注释规范是参与Go开源项目的必备技能。
文档注释支持部分Markdown语法(如`code`、*italic*、**bold**),但非全部。例如:
// Returns a [slice](https://pkg.go.dev/builtin#slice) of data. // Use `gofmt` to format code.
此处[slice]会被解析为链接,但复杂表格、列表可能失效。官方建议仅用基础Markdown,复杂内容改用代码块说明。
三、Go文档注释与godoc工具链深度解析
Go语言内置的文档生成工具链是其生态优势之一。核心组件包括:godoc(命令行工具)、GoDoc.org(在线文档服务)、IDE集成提示(如VS Code的Go插件)。三者均依赖**文档注释**,通过静态分析提取注释内容,构建API文档树。以下为工作原理与最佳实践:
3.1 godoc工具链工作流程
当执行“godoc -http=:6060”启动Web服务时,流程如下:
- 扫描当前目录及子目录下的.go文件
- 解析AST(抽象语法树),识别声明节点(func、type、var等)
- 提取紧邻声明前的注释块,作为文档注释
- 解析注释中的Markdown语法(基础支持)
- 生成HTML页面,结构包括:包说明、类型/函数索引、源码链接
关键点:文档注释必须位于声明语句之前,且中间**无空行**。此规则确保工具准确关联注释与声明。例如:
// Package math provides basic constants and functions.
package math
// Pi is the ratio of a circle's circumference to its diameter.
const Pi = 3.14159
// Sqrt returns the square root of x.
func Sqrt(x float64) float64 { ... }
执行“godoc math Sqrt”将显示Sqrt函数文档;在浏览器访问http://localhost:6060/pkg/math/可查看完整包文档。
3.2 文档注释高级技巧
为提升文档质量,开发者可采用以下技巧:
- 使用“@see”链接相关文档:
// See also: [http://golang.org/pkg/math/](http://golang.org/pkg/math/) for related functions.
- 添加代码示例(go doc示例):
// Example: // func ExampleMax() { // fmt.Println(Max(3, 5)) // Output: 5 // }执行“go doc -src Max”可查看示例。 - 声明废弃(Deprecation):
// Deprecated: Use NewMax instead. Will be removed in v2.0.
工具虽不自动处理,但可被IDE高亮提示。
示例代码需放在文档注释末尾,以“// Example:”开头,且函数名需为“Example+目标函数名”(如“ExampleMax”)。当执行“go test -doc”时,这些示例会被编译并运行,验证其正确性——这是Go文档的**硬性校验机制**,确保示例代码永不过时。
3.3 GoDoc.org在线文档生成
当项目托管于GitHub/Gitee等平台时,访问[https://pkg.go.dev/](https://pkg.go.dev/)(Go官方文档站)可自动生成文档。流程为:
- 用户访问pkg.go.dev/用户名/项目名
- 服务端拉取最新commit,解析所有.go文件
- 提取文档注释,生成HTML
- 缓存结果,支持版本切换(通过tag/commit)
关键要求:项目根目录需有go.mod文件(Go Modules),否则无法识别模块路径。文档更新依赖新版本发布(tag),非实时同步。开发者可通过提交PR修正注释,经合并后触发新版本生成。
3.4 IDE集成提示
主流IDE(VS Code、GoLand)均集成go doc功能:
- 鼠标悬停函数名 → 显示文档注释摘要
- Ctrl+点击函数名 → 跳转至源码,附带完整注释
- 自动补全参数名 → 基于文档注释中的参数说明
此功能依赖本地gopls语言服务器,其启动时扫描工作区所有.go文件,构建文档索引。因此,文档注释质量直接影响IDE提示体验。建议为公共API(exported identifiers)编写完整文档,内部函数可简化。
3.5 文档注释常见错误
错误1:注释与声明间有空行
// 这是文档注释
func Foo() {} // → 失效!中间有空行
修正:删除空行,或改用多行注释(但多行注释不被godoc识别为文档注释)。
错误2:未以被注释项开头
// Returns the larger value.
func Max(a, b int) int { ... }
修正:改为“Max returns the larger value.”。首句需包含被注释项名称,便于索引。
错误3:过度注释
// Max is a function that takes two integers and returns the larger one.
// It compares a and b, and returns a if a > b, otherwise returns b.
// This is a very simple implementation.
func Max(a, b int) int { ... }
修正:仅保留首句摘要。读者可直接查看函数体理解实现,无需冗余解释。
遵循**go注释的标准语言**文档规范,可显著提升项目专业性与协作效率。开源项目中,文档注释缺失是PR被拒的常见原因,开发者需高度重视。
四、Go注释相关工具链与自动化实践
Go生态提供了丰富的工具链,用于注释的自动化处理、校验与生成。以下为**go注释的标准语言**实践核心工具:
4.1 gofmt:格式化与注释调整
gofmt是Go官方代码格式化工具,其功能远超“缩进调整”:
- 自动对齐行尾注释:将“x := 1//comment”修正为“x := 1 // comment”
- 折叠多行注释:将连续单行注释合并为多行注释块(需配置)
- 删除无用注释:移除“//”后无内容的行(需用“-s”参数)
关键命令:
gofmt -w . # 格式化当前目录所有.go文件 gofmt -d file.go # 显示格式化差异(不写入文件) gofmt -s file.go # 简化代码(含删除空注释)
例如,原始代码:
package main
// 这是注释1
// 这是注释2
// 这是注释3
func main() {x:=1//init}
执行“gofmt -w .”后:
package main
// 这是注释1
// 这是注释2
// 这是注释3
func main() {
x := 1 // init
}
注释被保留,行尾注释自动添加空格。此行为确保团队代码风格统一,是CI/CD流程的必备检查项。
4.2 goimports:导入管理与注释清理
goimports在gofmt基础上,新增功能:
- 自动添加/删除import语句
- 按字母排序import分组(标准库、第三方、本地)
- 删除无效注释(如“// unused”标记的变量注释)
与gofmt配合使用:
goimports -w .
在VS Code中,可通过设置“go.formatTool: goimports”启用自动格式化。
4.3 golangci-lint:注释质量校验
golangci-lint是Go生态最流行的Lint工具,集成多个检查器,其中与注释相关的核心检查器包括:
- golint:检查文档注释规范(如首句格式、缺失说明)
- revive:可配置规则,如“func comment must start with function name”
- gochecknocomments:检测无用注释(如被注释的代码已废弃)
安装与使用:
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest golangci-lint run ./...
典型警告示例:
main.go:5:1: comment on exported function Foo should be of the form "Foo ..." (golint)
// Foo returns bar
func Foo() string { ... }
修正为:// Foo returns bar value.
通过CI集成golangci-lint(如GitHub Actions),可自动化注释规范检查,确保**go注释的标准语言**持续落地。
4.4 文档生成工具
除godoc外,社区工具进一步增强文档生成能力:
- swaggo/swag:为Go API生成Swagger文档(需在注释中添加@summary等标记)
- go-apidiff:比较API变更,高亮注释修改
- goreadme:生成README.md,基于包内文档注释
swaggo示例:
// @Summary Get user by ID
// @Tags users
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} User
// @Router /users/{id} [get]
func GetUser(c *gin.Context) { ... }
执行“swag init”生成swagger.json,供Swagger UI渲染。此功能将注释转化为交互式API文档,是微服务开发的**go注释的标准语言**延伸实践。
4.5 IDE插件增强
主流IDE插件提供深度注释支持:
- VS Code Go插件:悬停提示、快速修复(如补全文档注释)、TODO高亮
- GoLand:智能补全文档注释(Alt+Enter → Add documentation comment)、注释模板
GoLand的“Code → Generate → Documentation Comment”可自动生成模板:
// FunctionNameDescription ... // // Parameters: // - paramName: description // // Returns: // - type: description
开发者仅需填充细节,大幅减少重复劳动。
工具链使用建议:将gofmt、goimports、golangci-lint集成至开发流程(如Git Hooks、IDE自动保存触发),实现注释规范的**无感维护**。这才是**go注释的标准语言**工程化的终极形态。
五、Go注释最佳实践与行业经验总结
基于Go开源项目(如Kubernetes、Docker、Prometheus)的注释分析,结合社区共识,总结以下**go注释的标准语言**最佳实践:
5.1 全局原则
- 注释为代码服务,非代码替代:注释解释“为什么”,而非“是什么”。例如:
// 使用互斥锁保护共享变量,避免竞态条件 mu.Lock() defer mu.Unlock() count++
此注释说明加锁原因,比“count++”更高效。 - 优先注释公共API:exported函数、类型、变量必须有文档注释;内部函数可简化注释,但关键逻辑需说明。
- 注释随代码更新:修改逻辑时同步更新注释,避免“注释失真”。版本控制中,注释变更应与代码变更同PR提交。
5.2 函数注释规范
函数文档注释必须包含:
- 首句摘要(以函数名开头)
- 参数说明(格式:paramName ...)
- 返回值说明(格式:Returns ...)
- 错误处理(如适用)
- 并发安全(如适用)
示例:
// ReadConfig loads configuration from file path.
//
// Parameters:
// - path: configuration file path
// - validator: optional config validator function
//
// Returns:
// - Config: parsed configuration
// - error: non-nil if path is invalid or parsing fails
//
// Concurrency:
// This function is safe for concurrent use.
func ReadConfig(path string, validator func(Config) error) (Config, error) { ... }
此结构确保文档工具与IDE提示完整,读者无需跳转源码即可理解函数用法。
5.3 类型与变量注释
类型注释需说明其用途与约束:
// Config holds application settings.
//
// Fields:
// - Timeout: request timeout duration (default: 30s)
// - Retries: max retry count (default: 3)
// - Debug: enable debug mode (default: false)
type Config struct {
Timeout time.Duration
Retries int
Debug bool
}
变量注释强调初始化值与用途:
const ( defaultTimeout = 30 * time.Second // default request timeout maxRetries = 10 // maximum retry attempts )
5.4 复杂逻辑注释
对算法、边界条件、性能优化等,需添加分段注释:
func fib(n int) int {
// Handle base cases
if n < 0 {
panic("fib: negative input")
}
if n < 2 {
return n
}
// Iterative calculation to avoid stack overflow
a, b := 0, 1
for i := 2; i <= n; i++ {
a, b = b, a+b
}
return b
}
分段注释比长段注释更易读,符合Go“简洁即美”哲学。
5.5 高频反模式
反模式1:注释即代码
// if a > b, return a, else return b
func Max(a, b int) int {
if a > b {
return a
}
return b
}
此注释冗余,因代码自解释。应删除或改为“Handles edge cases where a == b”。
反模式2:注释过时
// Returns the sum of two integers.
func Max(a, b int) int { ... } // 实际返回最大值,非和
过时注释比无注释更危险!需定期用golangci-lint校验。
反模式3:过度注释
// This function is designed to compare two integer values.
// It uses a simple if-else statement to determine which value is larger.
// The function returns the larger value as an integer.
func Max(a, b int) int {
// Compare a and b
if a > b {
// Return a if it is larger
return a
} else {
// Otherwise, return b
return b
}
}
此注释充满废话。应精简为“Max returns the larger of two integers.”。
5.6 团队协作规范
- 制定团队《注释规范文档》,明确格式、标记词、禁忌
- PR审核清单包含“注释完整性检查”
- 使用golangci-lint + pre-commit hook自动校验
例如,团队规范可规定:
- 所有exported函数必须有文档注释
- 文档注释首句必须以函数名开头
- TODO需标注“@username”与截止日期
通过工具与流程结合,确保**go注释的标准语言**从个人习惯上升为团队文化。
六、Go注释常见问题(FAQ)与深度解答
基于Go社区高频问题,整理以下**go注释的标准语言**FAQ:
6.1 注释能否包含中文?
可以。Go语言规范允许注释中使用任意Unicode字符,包括中文。但需注意:
- 仅当文档注释首句为中文时,部分工具(如godoc)可能无法正确提取摘要(因依赖空格分词)
- 推荐中文注释用于内部文档,公共API仍用英文摘要
- 示例:
// 用户ID(非空字符串)合法
最佳实践:摘要用英文,细节用中文。例如:
// GetUser returns user info by ID.
// 参数:
// - id: 用户唯一标识
// 返回:
// - User: 用户对象
// - error: 未找到时返回ErrNotFound
func GetUser(id string) (User, error) { ... }
6.2 如何注释泛型函数?
泛型函数的文档注释需说明类型参数:
// Min returns the minimum of two values of the same type.
//
// Parameters:
// - a: first value
// - b: second value
//
// Type Parameters:
// - T: type of values, must be ordered
func Min[T constraints.Ordered](a, b T) T {
if a < b {
return a
}
return b
}
关键点:在文档注释中添加“Type Parameters:”分段,解释泛型约束。
6.3 注释中如何插入代码块?
文档注释中可插入代码块,格式为:
// Example: // result := Max(3, 5) // result = 5 // fmt.Println(result)
或使用反引号(但非必须):
// Use `gofmt` to format code.
注意:代码块需缩进4空格,否则不被识别为代码。
6.4 如何禁用特定注释检查?
通过golangci-lint配置,例如忽略TODO标记检查:
linters-settings:
revive:
rules:
- name: comment-spacings
disabled: true
或使用行内注释:
//nolint:golint // Temporary workaround for legacy code
func OldAPI() { ... }
6.5 注释会影响性能吗?
不会。Go编译器在词法分析阶段即丢弃注释,不参与编译。执行“go build -gcflags=-m”可验证:注释未出现在AST中。
但过度长注释会增加源文件体积,轻微影响编译速度(微秒级),可忽略。
6.6 如何为包编写文档?
在包目录下新建doc.go文件,写入包说明:
// Package math provides basic mathematical functions and constants. // // This package is part of the standard library and is always available. // For advanced operations, see math/big. package math
执行“go doc math”将显示此文档,作为包首页说明。
6.7 注释能否用于条件编译?
不能。条件编译使用“// +build”标记(Go 1.17+推荐用“//go:build”),属于编译指令,与注释无关:
//go:build windows // +build windows package main
此标记在编译时生效,但不会被godoc提取为文档。
更多FAQ见Go官方文档:[https://go.dev/doc/comment](https://go.dev/doc/comment)