本文翻译自 go 官方文档，介绍了 go 语言中文档注释相关的内容。go 开发者在开发项目时，可以按照文章中规定的范式编写文档，方便进行团队协作。以下为翻译内容：
“文档注释” 是在包、常量、函数、类型和变量声明前紧跟着的，没有新行的注释。所有的可导出（首字母大写）元素都应有注释。
go/doc 和 go/doc/comment 包提供了从 go 源码中提取文档的能力，很多工具都使用了这种能力。go doc 命令查询并打印给定包或元素的文档注释。pkg.go.dev 网站展示公开 go 包的文档注释（当其 license 允许这种用途时）。网站由 golang.org/x/pkgsite/c… 程序提供服务。它也能在本地运行，以查看私有包的文档注释，或者在无网络的情况下查看文档注释。language server gopls 在使用 IDE 编辑 go 代码时提供文档。
本页剩余内容记录了编写 go 文档注释的范式。
译者注：范式部分可以详细地读一下，对于怎样高效地写出清晰的文档很有帮助。
包（Packages）
每个包都应有包注释，以介绍包的内容。它提供了整个包相关的信息，且通常包含包的预期使用方式。尤其是在大型的包中，包注释能为包中最重要的 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".
对于包含多个文件的包，包注释应该只写在其中一个原文件中。如果多个文件都有文档注释，它们会被拼接，形成整个包的大注释。
命令行工具（Commands）
给命令行工具的包注释也是类似的，但在包中说明的不是包内元素而是程序的行为。包注释习惯上应以程序的名称开头。因为在英语句子的开头，所以注释应该首字母大写。例如这是修改后的 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
这段注释的开头按 语义分行 的方式编写。语义分行就是无论长短，一句注释占一行。这样能在开发过程中让 git 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 中会以代码字体展示（后面的语法章节中会展示详情）。
类型（Types）
类型的文档注释应该解释该类型的每个实例代表或提供了什么。若 API 简单的话文档注释可以非常短。例如：
package zip
// A Reader serves content from a ZIP archive.
type Reader struct {
...
}
默认情况下，代码的使用者应期望一种类型一次只能在一个协程中安全使用。如果一个类型提供了更强的保证，那就应该在文档注释中说明。例如：
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
...
}
就像包（前）和函数（后）一样，类型的文档注释以命名声明元素的完整句子开头。
与软件包（上图）和funcs（下图）一样，类型的文档注释以命名声明符号的完整句子开始。明确的主题通常使措辞更清晰，并使文本更容易被搜索，无论是在网页还是命令行上。例如：
$ 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
$
函数（Funcs）
函数的文档注释应该解释函数返回什么，或者对于需要副作用的函数，它做了什么。命名的参数和返回值可以直接在注释中引用，不需要任何反引号等特殊语法。（这种惯例的后果是，像 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) {
...
}
（译者注：中文文档不需要关注这个问题）返回 boolean 类型的函数的文档注释通常使用 "reports whether" 描述，"or not" 是不必要的，例如：
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 示例一样。这样能防止影响文档观看体验。
这些规则对纯函数和方法都适用。对于方法来说，在列出一个类型的所有方法时，使用相同的 receiver 名可以避免不必要的差异：
$ 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 的顶层函数。这种函数可能有额外的 error 返回值。它们被假设为T的构造函数，与类型 T 及其方法一同展示。
默认情况下，代码的使用者可以假设顶层函数可以安全地在多个协程中被调用。这个事实不需要特别声明。
另一方面，如上一节所述。以任何方式使用类型的实例，包括调用方法，通常假定为一次仅在单个协程中使用。如果方法可以被并发使用，且没有在类的文档注释中记录，则应将其记录在每个方法的评论中。例如：
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) {
...
}
因为文档注释没有提到具体使用了那个排序算法。之后可以很容易地改为使用另一种不同的算法实现。
常量（Consts）
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
...
)
（关于 HTML 演示，请参阅 pkg.go.dev/regexp/synt…）。
变量（Vars）
变量的文档注释约定与常量的相同。例如，以下是一组变量：
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 删除了文档注释中的前导和尾随空白行。如果文档注释中的所有行都以相同的空格或\t序列开头，gofmt 会删除该前缀。
段落（Paragraphs）
一个段落是一段未缩进的非空白行。我们已经看到了许多段落的例子。
一对连续的反向引号 (` U+0060) 被解释为 Unicode 左引号 (“ U+201C)，一对连续的单引号 (' U+0027) 被解释为Unicode 右引号 (” U+201D)。
gofmt 保留段落文本中的换行符：它对文本不会重新换行。如前所述，这允许使用 语义分行。gofmt 将段落之间重复的空白行替换为单个空白行。gofmt 同样将连续的反引号或单引号重新格式化为它们的 Unicode 形式。
标题（Headings）
标题是以井号（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。在此之前，标题通过满足某些条件的单行段落隐式识别，最明显的是缺乏任何终止标点符号。
gofmt 将早期版本的 go 中视为 隐式标题的行 重新格式化，以使用 # 标题代替。如果重新格式化不合适——也就是说，如果该行不是标题——使其成为段落的最简单方法是引入句号或冒号等终止标点符号，或将其分成两行。
链接（Links）
脚注被定义为一段未缩进的非空白行，且每行都是 "[文本]:URL" 形式。在同一文档注释中的其他文本中，"[文本]" 表示使用给定文本的 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.org/doc/articles/json_and_go.html
package json
通过将 URL 保存在单独的部分，这种格式只会最小化地中断实际文本流。它还大致匹配 Markdown 快捷方式参考链接格式，没有可选的标题文本。
如果没有相应的 URL 声明，那么（下一节中描述的文档链接除外）"[文本]" 不是超链接，显示时会保留方括号。每个文档评论都是独立考虑的：一个注释中的脚注定义不会影响其他注释。
尽管脚注定义块可能与普通段落交错，但 gofmt 会将脚注定义移动到文档注释的末尾。脚注会分为最多两部分：一是被引用的所有脚注；二是未被引用的所有脚注。分块使未使用的脚注易于发现，然后修改（当链接或定义有错别字时）或删除（当定义不再被需要时）。
被识别为URL的纯文本会自动链接到 HTML 渲染中。
文档链接（Doc links）
文档链接是 "[Name1]" 或 "[Name1.Name2]" 形式的链接，引用当前软件包中可导出的标识符，或 "[pkg]"、"[pkg.Name1]" 或 "[pkg.Name.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" 要么是完整的导入路径，要么是现有 import 的假定包名。假定包名要么是重命名的 import 包名，要么是 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、泛型和数组类型出现问题，文档链接前后必须有标点符号、空格、制表符或行的开头或结尾。例如，文本 "map[ast.Expr]TypeAndValue" 不包含文档链接。
列表（Lists）
列表是一段缩进或空白行（否则将是一个代码块，如下节所述），其中第一行以项目符号列表标记或编号列表标记开头。
项目符号列表标记是星号、加号、破折号或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 保留但不要求列表和上一段之间的空行。它在列表和后续段落或标题之间插入一行空白行。
代码块（Code blocks）
代码块是一段不以项目符号列表符或编号列表符开头的缩进或空白行。它被渲染为预格式化文本（在 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 doc 注释不支持嵌套列表，所以 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.
