Go go/doc.ToText 如何把注释格式化成终端文本

如果命令行工具已经拿到一段 Go 文档注释，想把它变成带段落、列表和代码块缩进的纯文本，go/doc.ToText 的定位很清楚：它接收一个 io.Writer，再按照 prefix、codePrefix 和 width 把注释写出去。真正需要注意的是，ToText 已被官方标记为弃用；新代码通常应使用带包上下文的 Package.Text，或解析后配置 comment.Printer。

这篇文章把它当成一种“终端文本适配器”来理解：输入是 Go 注释语法，输出是人能在终端中阅读的纯文本，参数负责版式，包上下文负责链接语义。这样既能读懂旧代码，也能知道什么时候不该继续扩展旧调用。

模式命名：ToText 是注释到终端文本的格式化边界

go/doc 用来从 Go AST 中提取源代码文档。旧的 ToText 函数则只处理已经拿到的注释文本：它不会替你生成 HTML，也不负责把一整个包重新解析成文档模型。它把格式化结果写入调用方给出的 io.Writer，所以 bytes.Buffer、文件或标准输出都可以作为承载对象。

这个边界很适合小型命令行工具：调用方决定输出去哪里，ToText 决定段落、列表、预格式化代码块和换行如何变成纯文本。它的适用压力是“我已经有注释字符串，只想按 Go 文档规则输出”，而不是“我要构建完整的 API 文档网站”。

适用压力：三个参数分别解决什么版式问题

函数签名是 ToText(w io.Writer, text, prefix, codePrefix string, width int)。可以把三个格式化参数拆成普通行、代码块行和文本宽度三种压力：

这里最容易混淆的是 codePrefix。它不是在普通前缀后面再叠加一层，而是代码块行使用的独立前缀；在现代 comment.Printer 中，TextCodePrefix 为空时才会默认成 TextPrefix + "\t"。如果你的终端输出要求代码块和普通段落左边界不同，就应该明确设置它。

典型实现：让输出容器和版式参数显式出现

下面的写法适合维护旧工具或兼容旧接口。示例把注释写入内存，再打印结果；代码中的中文注释说明了输出容器、前缀和行宽的职责。

package main

import (
    "bytes"
    "fmt"
    "go/doc"
    "os"
)

func main() {
    text := "读取配置文件。\n\n    path := os.Getenv(\"APP_CONFIG\")\n"
    var buf bytes.Buffer

    // 普通段落使用 prefix，代码块使用独立的 codePrefix。
    doc.ToText(&buf, text, "| ", "|   ", 72)

    // 统一从 Writer 取出纯文本，便于继续写入终端或文件。
    fmt.Print(buf.String())
}

这里的 72 不是“每行字节数”，而是给文本排版器使用的宽度概念；终端程序若混合中英文，应该把它当作显示布局的近似边界，而不是对 UTF-8 字节切片。若你设置了 prefix，可用宽度还要为前缀留出空间，否则视觉上会比预期更拥挤。

这个模式的好处是职责单一：bytes.Buffer 负责收集，ToText 负责格式化，调用方最后决定输出目的地。它的代价也很明确：ToText 不知道这段注释属于哪个包，因此无法可靠识别依赖包上下文的文档链接。

反例：把 ToText 当成完整文档链接解析器

Go 文档注释不仅有普通文本，也支持链接、标题、列表和预格式化文本。可是官方文档明确指出，ToText 无法识别依赖包上下文的文档链接，因为它的参数里没有当前包的信息。仅仅把 width 调大、把 prefix 设为空，并不会补上缺失的语义。

因此，下面两种需求要分开判断：

• 只想得到稳定的终端纯文本：旧调用可以继续工作，重点是参数和写入错误。
• 希望把 [io.Reader]、当前包符号或外部包符号解析成准确文档链接：应该先让 go/doc 建立包上下文，再使用现代文本打印接口。

这也是一个典型的架构取舍：ToText 的输入简单、接入成本低，但语义信息少；Package.Text 或 comment.Printer.Text 的输入准备更完整，却能把链接识别和版式配置放在同一条链路上。

后果：何时迁移到 Package.Text，何时配置 Printer

官方建议的最短迁移路径是使用 Package.Text(text)。它仍然返回纯文本字节，但调用者不再手写 io.Writer 和三参数格式化入口；更重要的是，Package 提供了识别文档链接所需的上下文。

// Package.Text 适合接受默认的 Go 文本格式化规则。
output := p.Text(commentText)
if _, err := os.Stdout.Write(output); err != nil {
    // 写终端失败时把错误交给上层，而不是静默丢弃。
    return err
}

如果终端工具仍然需要自定义前缀、代码块缩进或宽度，就使用 p.Parser()、p.Printer() 这条更完整的链路：

// 解析时保留包上下文，让文档链接可以按当前包规则处理。
parser := p.Parser()
doc := parser.Parse(commentText)

printer := p.Printer()
// 普通行、代码块行和换行宽度分别独立配置。
printer.TextPrefix = "| "
printer.TextCodePrefix = "|   "
printer.TextWidth = 72

output := printer.Text(doc)
if _, err := os.Stdout.Write(output); err != nil {
    // 把标准输出错误返回给调用者，便于命令行程序设置退出状态。
    return err
}

comment.Printer 的三个字段与旧参数一一对应：TextPrefix 对应普通行前缀，TextCodePrefix 对应代码块行前缀，TextWidth 对应换行宽度。它还允许把文档链接 URL 的计算交给 DocLinkURL，这正是旧 ToText 无法表达的包级信息。

反例后果：只改参数，仍然解决不了语义缺口

有些工具迁移时只把 width 从 80 改成 120，或把 codePrefix 从制表符改成空格，就认为已经“升级”了。这样只能改变版式，不能改变 API 是否拥有包上下文的事实。

另一个常见误区是把负的 width 当成“自动适配当前终端窗口”。官方语义是负宽度表示不限制，并不意味着函数会读取终端列数。若命令行工具确实要适配窗口，应由外层读取窗口尺寸，再把决定后的宽度传给打印器。

最后，不要忽略 io.Writer 返回的写入错误。文档内容很短时错误不明显，但当输出通过管道、重定向或被提前关闭的文件承载时，静默丢弃错误会让调用者误以为格式化成功。

判断清单：把 ToText 放回合适的位置

1. 输入是否已经是去掉注释标记的文档文本？如果不是，先整理输入边界。
2. 输出是否只需要终端纯文本，而不是 HTML 或 Markdown？如果不是，选择对应的现代打印方法。
3. 普通行、代码块行是否需要不同缩进？需要时明确设置 prefix 和 codePrefix。
4. 宽度是否由外层决定？把终端窗口测量和文本格式化分开，不把负宽度误解成自动检测。
5. 文章里的链接是否依赖当前包或外部包？如果依赖，就优先迁移到 Package.Text 或配置 comment.Printer。
6. 输出目标是否可能失败？检查 Writer.Write 返回的错误，让命令行工具能正确报告失败。

归纳起来，go/doc.ToText 仍然适合解释旧代码的“参数到版式”关系，但不应被当成新的文档链接解析入口。默认纯文本输出用 Package.Text，需要前缀、代码块缩进或宽度控制时用 comment.Printer.Text，这条迁移路径能保留终端体验，也补上包上下文。

相关问题

ToText 的 width 是字节数吗？

不是。现代 comment.Printer.TextWidth 的文档说明按 Unicode code point 计算，换行符和文本前缀不计入该宽度。它不是对 UTF-8 字节数组做简单截断。

codePrefix 为空会怎样？

在现代 comment.Printer 中，空的 TextCodePrefix 会默认使用 TextPrefix + "\t"。如果希望代码块行使用固定空格或特殊竖线，应显式指定。

Package.Text 能不能自定义终端前缀？

Package.Text 适合默认格式化；需要自定义前缀、代码块前缀或宽度时，应改用 p.Parser() 加 p.Printer() 并设置对应字段。

ToText 可以输出 HTML 吗？

不能。ToText 的职责是格式化纯文本；ToHTML 曾用于 HTML，但官方同样建议使用带包上下文的现代打印链路。