Go 文档注释
“文档注释”是紧接在顶级包、const、func、type 和 var 声明之前出现的注释，中间没有换行符。每个导出的（大写）名称都应有文档注释。
go/doc 和 go/doc/comment 包提供了从 Go 源代码中提取文档的功能，并且各种工具都利用了此功能。 go doc 命令查找并打印给定包或符号的文档注释。（符号是顶级 const、func、type 或 var。）Web 服务器 pkg.go.dev 显示公共 Go 包的文档（当其许可证允许使用时）。为该网站提供服务的程序是 golang.org/x/pkgsite/cmd/pkgsite，它还可以在本地运行以查看私有模块的文档或在没有互联网连接的情况下查看。语言服务器 gopls 在 IDE 中编辑 Go 源文件时提供文档。
本页的其余部分记录了如何编写 Go 文档注释。
包
每个包都应该有一个包注释来介绍该包。它提供与整个包相关的信息，并且通常会为包设定预期。尤其是在大型包中，包注释可以简要概述 API 中最重要的部分，并根据需要链接到其他文档注释，这会很有帮助。
如果包很简单，包注释可以很简短。例如
// Package path implements utility routines for manipulating slash-separated
// paths.
//
// The path package should only be used for paths separated by forward
// slashes, such as the paths in URLs. This package does not deal with
// Windows paths with drive letters or backslashes; to manipulate
// operating system paths, use the [path/filepath] package.
package path
[path/filepath] 中的方括号创建了 文档链接。
如本示例所示，Go 文档注释使用完整句子。对于包注释，这意味着 第一个句子 以“Package
对于多文件包，包注释只能在一个源文件中。如果多个文件有包注释，它们会被连接起来，为整个包形成一个大型注释。
命令
命令的包注释类似，但它描述程序的行为，而不是包中的 Go 符号。按照惯例，第一个句子以程序本身的名称开头，大写，因为它位于句子的开头。例如，以下是 gofmt 的包注释的缩写版
/*
Gofmt formats Go programs.
It uses tabs for indentation and blanks for alignment.
Alignment assumes that an editor is using a fixed-width font.
Without an explicit path, it processes the standard input. Given a file,
it operates on that file; given a directory, it operates on all .go files in
that directory, recursively. (Files starting with a period are ignored.)
By default, gofmt prints the reformatted sources to standard output.
Usage:
gofmt [flags] [path ...]
The flags are:
-d
Do not print reformatted sources to standard output.
If a file's formatting is different than gofmt's, print diffs
to standard output.
-w
Do not print reformatted sources to standard output.
If a file's formatting is different from gofmt's, overwrite it
with gofmt's version. If an error occurred during overwriting,
the original file is restored from an automatic backup.
When gofmt reads from standard input, it accepts either a full Go program
or a program fragment. A program fragment must be a syntactically
valid declaration list, statement list, or expression. When formatting
such a fragment, gofmt preserves leading indentation as well as leading
and trailing spaces, so that individual sections of a Go program can be
formatted by piping them through gofmt.
*/
package main
注释的开头使用 语义换行 编写，其中每个新句子或长短语都单独占一行，这可以使 diff 在代码和注释演变时更容易阅读。后面的段落碰巧没有遵循此惯例，而是手动换行。无论哪种方式最适合你的代码库都可以。无论哪种方式，go doc 和 pkgsite 在打印文档注释文本时都会重新换行。例如
$ go doc gofmt
Gofmt formats Go programs. It uses tabs for indentation and blanks for
alignment. Alignment assumes that an editor is using a fixed-width font.
Without an explicit path, it processes the standard input. Given a file, it
operates on that file; given a directory, it operates on all .go files in that
directory, recursively. (Files starting with a period are ignored.) By default,
gofmt prints the reformatted sources to standard output.
Usage:
gofmt [flags] [path ...]
The flags are:
-d
Do not print reformatted sources to standard output.
If a file's formatting is different than gofmt's, print diffs
to standard output.
...
缩进行作为预格式文本处理：它们不会重新换行，并且在 HTML 和 Markdown 演示中以代码字体打印。（下面的 语法 部分提供了详细信息。）
类型
类型的文档注释应说明该类型的每个实例表示或提供的内容。如果 API 很简单，则文档注释可以很短。例如
package zip
// A Reader serves content from a ZIP archive.
type Reader struct {
...
}
默认情况下，程序员应期望一个类型一次仅能安全地供一个 goroutine 使用。如果一个类型提供了更强的保证，则文档注释应说明它们。例如
package regexp
// Regexp is the representation of a compiled regular expression.
// A Regexp is safe for concurrent use by multiple goroutines,
// except for configuration methods, such as Longest.
type Regexp struct {
...
}
Go 类型还应旨在使零值具有有用的含义。如果它不明显，则应记录该含义。例如
package bytes
// A Buffer is a variable-sized buffer of bytes with Read and Write methods.
// The zero value for Buffer is an empty buffer ready to use.
type Buffer struct {
...
}
对于具有导出字段的结构，文档注释或每个字段的注释应说明每个导出字段的含义。例如，此类型的文档注释说明了这些字段
package io
// A LimitedReader reads from R but limits the amount of
// data returned to just N bytes. Each call to Read
// updates N to reflect the new amount remaining.
// Read returns EOF when N <= 0.
type LimitedReader struct {
R Reader // underlying reader
N int64 // max bytes remaining
}
相比之下，此类型的文档注释将解释留给了每个字段的注释
package comment
// A Printer is a doc comment printer.
// The fields in the struct can be filled in before calling
// any of the printing methods
// in order to customize the details of the printing process.
type Printer struct {
// HeadingLevel is the nesting level used for
// HTML and Markdown headings.
// If HeadingLevel is zero, it defaults to level 3,
// meaning to use <h3> and ###.
HeadingLevel int
...
}
与包（上面）和函数（下面）一样，类型的文档注释以命名声明符号的完整句子开头。明确的主语通常使措辞更清晰，并且使文本更容易搜索，无论是在网页上还是在命令行上。例如
$ go doc -all regexp | grep pairs
pairs within the input string: result[2*n:2*n+2] identifies the indexes
FindReaderSubmatchIndex returns a slice holding the index pairs identifying
FindStringSubmatchIndex returns a slice holding the index pairs identifying
FindSubmatchIndex returns a slice holding the index pairs identifying the
$
函数
函数的文档注释应说明函数返回的内容，或者对于因副作用而调用的函数，说明它执行的操作。命名的参数和结果可以在注释中直接引用，而无需任何特殊语法，如反引号。（此约定的结果是，通常避免使用可能被误认为普通单词的名称，如 a。）例如
package strconv
// Quote returns a double-quoted Go string literal representing s.
// The returned string uses Go escape sequences (\t, \n, \xFF, \u0100)
// for control characters and non-printable characters as defined by IsPrint.
func Quote(s string) string {
...
}
和
package os
// Exit causes the current program to exit with the given status code.
// Conventionally, code zero indicates success, non-zero an error.
// The program terminates immediately; deferred functions are not run.
//
// For portability, the status code should be in the range [0, 125].
func Exit(code int) {
...
}
文档注释通常使用短语“报告是否”来描述返回布尔值的函数。短语“或不”是不必要的。例如
package strings
// HasPrefix reports whether the string s begins with prefix.
func HasPrefix(s, prefix string) bool
如果文档注释需要解释多个结果，则命名结果可以使文档注释更易于理解，即使这些名称未用于函数主体中。例如
package io
// Copy copies from src to dst until either EOF is reached
// on src or an error occurs. It returns the total number of bytes
// written and the first error encountered while copying, if any.
//
// A successful Copy returns err == nil, not err == EOF.
// Because Copy is defined to read from src until EOF, it does
// not treat an EOF from Read as an error to be reported.
func Copy(dst Writer, src Reader) (n int64, err error) {
...
}
相反，当不需要在文档注释中命名结果时，它们通常也会在代码中省略，如上面的 Quote 示例中所示，以避免使演示文稿杂乱。
这些规则都适用于普通函数和方法。对于方法，使用相同的接收器名称可以避免在列出类型的全部方法时出现不必要的差异
$ go doc bytes.Buffer
package bytes // import "bytes"
type Buffer struct {
// Has unexported fields.
}
A Buffer is a variable-sized buffer of bytes with Read and Write methods.
The zero value for Buffer is an empty buffer ready to use.
func NewBuffer(buf []byte) *Buffer
func NewBufferString(s string) *Buffer
func (b *Buffer) Bytes() []byte
func (b *Buffer) Cap() int
func (b *Buffer) Grow(n int)
func (b *Buffer) Len() int
func (b *Buffer) Next(n int) []byte
func (b *Buffer) Read(p []byte) (n int, err error)
func (b *Buffer) ReadByte() (byte, error)
...
此示例还显示了返回类型 T 或指针 *T 的顶级函数（可能带有附加错误结果）与类型 T 及其方法一起显示，假设它们是 T 的构造函数。
默认情况下，程序员可以假设从多个 goroutine 调用顶级函数是安全的；无需明确说明这一事实。
另一方面，如前一节所述，以任何方式（包括调用方法）使用类型实例通常被认为一次仅限于一个 goroutine。如果适合并发使用的那些方法未在类型的文档注释中记录，则应在每个方法的注释中记录。例如
package sql
// Close returns the connection to the connection pool.
// All operations after a Close will return with ErrConnDone.
// Close is safe to call concurrently with other operations and will
// block until all other operations finish. It may be useful to first
// cancel any used context and then call Close directly after.
func (c *Conn) Close() error {
...
}
请注意，函数和方法文档注释重点关注操作返回或执行的内容，详细说明调用者需要了解的内容。特殊情况可能特别重要，需要记录。例如
package math
// Sqrt returns the square root of x.
//
// Special cases are:
//
// Sqrt(+Inf) = +Inf
// Sqrt(±0) = ±0
// Sqrt(x < 0) = NaN
// Sqrt(NaN) = NaN
func Sqrt(x float64) float64 {
...
}
文档注释不应解释内部细节，例如当前实现中使用的算法。最好将这些内容留在函数体内的注释中。当该细节对调用者特别重要时，可以给出渐近时间或空间界限。例如
package sort
// Sort sorts data in ascending order as determined by the Less method.
// It makes one call to data.Len to determine n and O(n*log(n)) calls to
// data.Less and data.Swap. The sort is not guaranteed to be stable.
func Sort(data Interface) {
...
}
由于此文档注释未提及使用哪种排序算法，因此将来可以更轻松地更改实现以使用不同的算法。
常量
Go 的声明语法允许对声明进行分组，在这种情况下，单个文档注释可以引入一组相关的常量，而各个常量仅由简短的行尾注释记录。例如
package scanner // import "text/scanner"
// The result of Scan is one of these tokens or a Unicode character.
const (
EOF = -(iota + 1)
Ident
Int
Float
Char
...
)
有时该组根本不需要文档注释。例如
package unicode // import "unicode"
const (
MaxRune = '\U0010FFFF' // maximum valid Unicode code point.
ReplacementChar = '\uFFFD' // represents invalid code points.
MaxASCII = '\u007F' // maximum ASCII value.
MaxLatin1 = '\u00FF' // maximum Latin-1 value.
)
另一方面，未分组的常量通常需要以完整句子开头的完整文档注释。例如
package unicode
// Version is the Unicode edition from which the tables are derived.
const Version = "13.0.0"
类型化常量显示在其类型的声明旁边，因此通常省略常量组文档注释，而采用类型的文档注释。例如
package syntax
// An Op is a single regular expression operator.
type Op uint8
const (
OpNoMatch Op = 1 + iota // matches no strings
OpEmptyMatch // matches empty string
OpLiteral // matches Runes sequence
OpCharClass // matches Runes interpreted as range pair list
OpAnyCharNotNL // matches any character except newline
...
)
（请参阅 pkg.go.dev/regexp/syntax#Op 以获取 HTML 演示。）
变量
变量的约定与常量的约定相同。例如，这里有一组分组变量
package fs
// Generic file system errors.
// Errors returned by file systems can be tested against these errors
// using errors.Is.
var (
ErrInvalid = errInvalid() // "invalid argument"
ErrPermission = errPermission() // "permission denied"
ErrExist = errExist() // "file already exists"
ErrNotExist = errNotExist() // "file does not exist"
ErrClosed = errClosed() // "file already closed"
)
和一个变量
package unicode
// Scripts is the set of Unicode script tables.
var Scripts = map[string]*RangeTable{
"Adlam": Adlam,
"Ahom": Ahom,
"Anatolian_Hieroglyphs": Anatolian_Hieroglyphs,
"Arabic": Arabic,
"Armenian": Armenian,
...
}
语法
Go 文档注释以简单的语法编写，支持段落、标题、链接、列表和预格式化代码块。为了使注释在源文件中保持轻量级和可读性，不支持字体更改或原始 HTML 等复杂功能。Markdown 爱好者可以将语法视为 Markdown 的简化子集。
标准格式化程序 gofmt 会重新格式化文档注释，以便对这些每个功能使用规范格式。Gofmt 旨在提高可读性，并让用户控制如何在源代码中编写注释，但会调整演示以使特定注释的语义含义更清晰，类似于在普通源代码中将 1+2 * 3 重新格式化为 1 + 2*3。
诸如 //go:generate 的指令注释不被视为文档注释的一部分，并且在呈现的文档中被省略。Gofmt 将指令注释移动到文档注释的末尾，前面加一个空行。例如
package regexp
// An Op is a single regular expression operator.
//
//go:generate stringer -type Op -trimprefix Op
type Op uint8
指令注释是一行匹配正则表达式 //(line |extern |export |[a-z0-9]+:[a-z0-9]) 的行。定义自己指令的工具应使用 //toolname:directive 形式。
Gofmt 会删除文档注释中的前导和尾随空白行。如果文档注释中的所有行都以相同的空格和制表符序列开头，则 gofmt 会删除该前缀。
段落
段落是未缩进的非空行的跨度。我们已经看到了许多段落的示例。
一对连续的反引号 (` U+0060) 被解释为 Unicode 左引号（“ U+201C），一对连续的单引号 (' U+0027) 被解释为 Unicode 右引号（” U+201D）。
Gofmt 保留段落文本中的换行符：它不会重新包装文本。这允许使用 语义换行符，如前所述。Gofmt 用单个空白行替换段落之间的重复空白行。Gofmt 还将连续的反引号或单引号重新格式化为其 Unicode 解释。
标题
标题是一行，以数字符号 (U+0023) 开头，然后是一个空格和标题文本。要被识别为标题，该行必须未缩进，并通过空白行与相邻的段落文本隔开。
例如
// Package strconv implements conversions to and from string representations
// of basic data types.
//
// # Numeric Conversions
//
// The most common numeric conversions are [Atoi] (string to int) and [Itoa] (int to string).
...
package strconv
另一方面
// #This is not a heading, because there is no space.
//
// # This is not a heading,
// # because it is multiple lines.
//
// # This is not a heading,
// because it is also multiple lines.
//
// The next paragraph is not a heading, because there is no additional text:
//
// #
//
// In the middle of a span of non-blank lines,
// # this is not a heading either.
//
// # This is not a heading, because it is indented.
在 Go 1.19 中添加了 # 语法。在 Go 1.19 之前，标题是通过满足特定条件的单行段落隐式识别的，最显着的是缺少任何终止标点符号。
Gofmt 重新格式化 早期版本的 Go 中被视为隐式标题的行，以改为使用 # 标题。如果重新格式化不合适，即如果该行不打算作为标题，则使其成为段落的最快捷方法是引入终止标点符号（如句号或冒号），或将其分成两行。
链接
当每行都采用 “[Text]: URL” 形式时，未缩进的非空行跨度定义链接目标。在同一文档注释中的其他文本中，“[Text]” 表示使用给定文本链接到 URL——在 HTML 中，<a href=“URL”>Text</a>。例如
// Package json implements encoding and decoding of JSON as defined in
// [RFC 7159]. The mapping between JSON and Go values is described
// in the documentation for the Marshal and Unmarshal functions.
//
// For an introduction to this package, see the article
// “[JSON and Go].”
//
// [RFC 7159]: https://tools.ietf.org/html/rfc7159
// [JSON and Go]: https://golang.ac.cn/doc/articles/json_and_go.html
package json
通过将 URL 保存在一个单独的部分中，此格式仅会极少地中断实际文本的流程。它还大致匹配 Markdown 快捷参考链接格式，但不包括可选标题文本。
如果没有相应的 URL 声明，则（除了下一节中描述的文档链接之外）“[Text]” 不是超链接，并且在显示时会保留方括号。每个文档注释被独立考虑：一个注释中的链接目标定义不会影响其他注释。
尽管链接目标定义块可以与普通段落交错，但 gofmt 会将所有链接目标定义移动到文档注释的末尾，最多分为两个块：第一个块包含注释中引用的所有链接目标，然后一个块包含注释中未引用的所有目标。单独的块使未使用的目标易于注意到并修复（如果链接或定义有错别字）或删除（如果不再需要定义）。
在 HTML 渲染中，被识别为 URL 的纯文本会自动链接。
文档链接
文档链接是形式为 “[Name1]” 或 “[Name1.Name2]” 的链接，用于引用当前包中导出的标识符，或 “[pkg]”、“[pkg.Name1]”或 “[pkg.Name1.Name2]” 来引用其他包中的标识符。
例如
package bytes
// ReadFrom reads data from r until EOF and appends it to the buffer, growing
// the buffer as needed. The return value n is the number of bytes read. Any
// error except [io.EOF] encountered during the read is also returned. If the
// buffer becomes too large, ReadFrom will panic with [ErrTooLarge].
func (b *Buffer) ReadFrom(r io.Reader) (n int64, err error) {
...
}
符号链接的方括号文本可以包含一个可选的前导星号，使其易于引用指针类型，例如 [*bytes.Buffer]。
在引用其他包时，“pkg” 可以是完整的导入路径或现有导入的假定包名称。假定的包名称要么是重命名导入中的标识符，要么是 goimports 假定的名称。（当该假设不正确时，goimports 会插入重命名，因此此规则应该适用于所有 Go 代码。）例如，如果当前包导入了 encoding/json，那么可以编写 “[json.Decoder]” 来代替 “[encoding/json.Decoder]” 以链接到 encoding/json 的 Decoder 的文档。如果包中的不同源文件使用相同名称导入了不同的包，那么该简写是模棱两可的，不能使用。
只有当“pkg” 以域名（带点的路径元素）开头或来自标准库的包之一（“[os]”、“[encoding/json]”等）时，才假定它是一个完整的导入路径。例如，[os.File] 和 [example.com/sys.File] 是文档链接（后者将是一个损坏的链接），但 [os/sys.File] 不是，因为标准库中没有 os/sys 包。
为了避免地图、泛型和数组类型出现问题，文档链接必须同时位于标点符号、空格、制表符或行的开头或结尾之前和之后。例如，文本“map[ast.Expr]TypeAndValue”不包含文档链接。
列表
列表是由缩进行或空白行（否则将是代码块，如下一节所述）组成的跨度，其中第一个缩进行以项目符号或数字列表标记开头。
项目符号是星号、加号、破折号或 Unicode 项目符号 (*、+、-、•；U+002A、U+002B、U+002D、U+2022)，后跟空格或制表符，然后是文本。在项目符号列表中，以项目符号开始的每一行都开始一个新的列表项。
例如
package url
// PublicSuffixList provides the public suffix of a domain. For example:
// - the public suffix of "example.com" is "com",
// - the public suffix of "foo1.foo2.foo3.co.uk" is "co.uk", and
// - the public suffix of "bar.pvt.k12.ma.us" is "pvt.k12.ma.us".
//
// Implementations of PublicSuffixList must be safe for concurrent use by
// multiple goroutines.
//
// An implementation that always returns "" is valid and may be useful for
// testing but it is not secure: it means that the HTTP server for foo.com can
// set a cookie for bar.com.
//
// A public suffix list implementation is in the package
// golang.org/x/net/publicsuffix.
type PublicSuffixList interface {
...
}
数字列表标记是任意长度的十进制数字，后跟句点或右括号，然后是空格或制表符，然后是文本。在数字列表中，以数字列表标记开始的每一行都开始一个新的列表项。项目编号保持原样，绝不重新编号。
例如
package path
// Clean returns the shortest path name equivalent to path
// by purely lexical processing. It applies the following rules
// iteratively until no further processing can be done:
//
// 1. Replace multiple slashes with a single slash.
// 2. Eliminate each . path name element (the current directory).
// 3. Eliminate each inner .. path name element (the parent directory)
// along with the non-.. element that precedes it.
// 4. Eliminate .. elements that begin a rooted path:
// that is, replace "/.." by "/" at the beginning of a path.
//
// The returned path ends in a slash only if it is the root "/".
//
// If the result of this process is an empty string, Clean
// returns the string ".".
//
// See also Rob Pike, “[Lexical File Names in Plan 9].”
//
// [Lexical File Names in Plan 9]: https://9p.io/sys/doc/lexnames.html
func Clean(path string) string {
...
}
列表项仅包含段落，而不包含代码块或嵌套列表。这避免了任何空间计数的细微差别，以及有关制表符在不一致缩进中占多少个空格的问题。
Gofmt 重新格式化项目符号列表，使用破折号作为项目符号标记，破折号前缩进两个空格，续行缩进四个空格。
Gofmt 重新格式化数字列表，在数字前使用一个空格，在数字后使用句号，续行再次缩进四个空格。
Gofmt 保留列表和前一段之间的空白行，但不强制要求。它在列表和后一段或标题之间插入一个空白行。
代码块
代码块是由缩进行或空白行组成的跨度，不以项目符号或数字列表标记开头。它被呈现为预格式化文本（HTML 中的 <pre> 块）。
代码块通常包含 Go 代码。例如
package sort
// Search uses binary search...
//
// As a more whimsical example, this program guesses your number:
//
// func GuessingGame() {
// var s string
// fmt.Printf("Pick an integer from 0 to 100.\n")
// answer := sort.Search(100, func(i int) bool {
// fmt.Printf("Is your number <= %d? ", i)
// fmt.Scanf("%s", &s)
// return s != "" && s[0] == 'y'
// })
// fmt.Printf("Your number is %d.\n", answer)
// }
func Search(n int, f func(int) bool) int {
...
}
当然，代码块通常还包含除代码之外的预格式化文本。例如
package path
// Match reports whether name matches the shell pattern.
// The pattern syntax is:
//
// pattern:
// { term }
// term:
// '*' matches any sequence of non-/ characters
// '?' matches any single non-/ character
// '[' [ '^' ] { character-range } ']'
// character class (must be non-empty)
// c matches character c (c != '*', '?', '\\', '[')
// '\\' c matches character c
//
// character-range:
// c matches character c (c != '\\', '-', ']')
// '\\' c matches character c
// lo '-' hi matches character c for lo <= c <= hi
//
// Match requires pattern to match all of name, not just a substring.
// The only possible returned error is [ErrBadPattern], when pattern
// is malformed.
func Match(pattern, name string) (matched bool, err error) {
...
}
Gofmt 将代码块中的所有行缩进一个制表符，替换非空白行中任何其他常见的缩进。Gofmt 还将在每个代码块之前和之后插入一个空白行，将代码块与周围的段落文本明确区分开来。
常见错误和陷阱
文档注释中任何缩进行或空白行的跨度都将被呈现为代码块的规则可以追溯到 Go 的最早时期。不幸的是，gofmt 中缺少对文档注释的支持导致了许多现有注释使用了缩进来创建代码块，而没有这种意思。
例如，godoc 一直将此非缩进列表解释为一个三行段落，后跟一个一行代码块
package http
// cancelTimerBody is an io.ReadCloser that wraps rc with two features:
// 1) On Read error or close, the stop func is called.
// 2) On Read failure, if reqDidTimeout is true, the error is wrapped and
// marked as net.Error that hit its timeout.
type cancelTimerBody struct {
...
}
这始终在 go doc 中呈现为
cancelTimerBody is an io.ReadCloser that wraps rc with two features:
1) On Read error or close, the stop func is called. 2) On Read failure,
if reqDidTimeout is true, the error is wrapped and
marked as net.Error that hit its timeout.
类似地，此注释中的命令是一行段落，后跟一行代码块
package smtp
// localhostCert is a PEM-encoded TLS cert generated from src/crypto/tls:
//
// go run generate_cert.go --rsa-bits 1024 --host 127.0.0.1,::1,example.com \
// --ca --start-date "Jan 1 00:00:00 1970" --duration=1000000h
var localhostCert = []byte(`...`)
这在 go doc 中呈现为
localhostCert is a PEM-encoded TLS cert generated from src/crypto/tls:
go run generate_cert.go --rsa-bits 1024 --host 127.0.0.1,::1,example.com \
--ca --start-date "Jan 1 00:00:00 1970" --duration=1000000h
此注释是一个两行段落（第二行是“{”），后跟一个六行缩进代码块和一个一行段落（“}”）。
// On the wire, the JSON will look something like this:
// {
// "kind":"MyAPIObject",
// "apiVersion":"v1",
// "myPlugin": {
// "kind":"PluginA",
// "aOption":"foo",
// },
// }
这在 go doc 中呈现为
On the wire, the JSON will look something like this: {
"kind":"MyAPIObject",
"apiVersion":"v1",
"myPlugin": {
"kind":"PluginA",
"aOption":"foo",
},
}
另一个常见的错误是非缩进的 Go 函数定义或块语句，类似地用“{”和“}”括起来。
Go 1.19 的 gofmt 中引入的文档注释重新格式化通过在代码块周围添加空行，使此类错误更加明显。
2022 年的分析发现，在公共 Go 模块中，只有 3% 的文档注释被 Go 1.19 gofmt 草案重新格式化。仅限于这些注释，大约 87% 的 gofmt 重新格式化保留了人们从阅读注释中推断出的结构；大约 6% 被这些非缩进列表、非缩进多行 shell 命令和非缩进大括号分隔的代码块绊倒。
基于此分析，Go 1.19 gofmt 应用了一些启发式方法，将非缩进行合并到相邻的缩进列表或代码块中。通过这些调整，Go 1.19 gofmt 将上述示例重新格式化为
// cancelTimerBody is an io.ReadCloser that wraps rc with two features:
// 1. On Read error or close, the stop func is called.
// 2. On Read failure, if reqDidTimeout is true, the error is wrapped and
// marked as net.Error that hit its timeout.
// localhostCert is a PEM-encoded TLS cert generated from src/crypto/tls:
//
// go run generate_cert.go --rsa-bits 1024 --host 127.0.0.1,::1,example.com \
// --ca --start-date "Jan 1 00:00:00 1970" --duration=1000000h
// On the wire, the JSON will look something like this:
//
// {
// "kind":"MyAPIObject",
// "apiVersion":"v1",
// "myPlugin": {
// "kind":"PluginA",
// "aOption":"foo",
// },
// }
此重新格式化使含义更清晰，并使文档注释在早期版本的 Go 中正确呈现。如果启发式方法做出错误的决定，可以通过插入空行来覆盖它，以清楚地将段落文本与非段落文本分隔开。
即使有这些启发式方法，其他现有注释也需要手动调整以纠正其呈现。最常见的错误是缩进换行的非缩进文本行。例如
// TODO Revisit this design. It may make sense to walk those nodes
// only once.
// According to the document:
// "The alignment factor (in bytes) that is used to align the raw data of sections in
// the image file. The value should be a power of 2 between 512 and 64 K, inclusive."
在这两个示例中，最后一行都是缩进的，使其成为一个代码块。解决方法是取消缩进这些行。
另一个常见的错误是没有缩进列表或代码块的换行缩进行。例如
// Uses of this error model include:
//
// - Partial errors. If a service needs to return partial errors to the
// client,
// it may embed the `Status` in the normal response to indicate the
// partial
// errors.
//
// - Workflow errors. A typical workflow has multiple steps. Each step
// may
// have a `Status` message for error reporting.
解决方法是缩进换行。
Go 文档注释不支持嵌套列表，因此 gofmt 重新格式化为
// Here is a list:
//
// - Item 1.
// * Subitem 1.
// * Subitem 2.
// - Item 2.
// - Item 3.
为
// Here is a list:
//
// - Item 1.
// - Subitem 1.
// - Subitem 2.
// - Item 2.
// - Item 3.
通常，重写文本以避免嵌套列表会改善文档，并且是最佳解决方案。另一种潜在的解决方法是混合列表标记，因为项目符号不会在编号列表中引入列表项，反之亦然。例如
// Here is a list:
//
// 1. Item 1.
//
// - Subitem 1.
//
// - Subitem 2.
//
// 2. Item 2.
//
// 3. Item 3.