Go comment.Printer 怎样把结构化注释转换为 Markdown

我在给 Go 文档工具增加 Markdown 导出时，最容易走弯路的地方是把“注释字符串”和“结构化文档”当成了同一层。go/doc/comment 的推荐路径是：先用 comment.Parser.Parse 得到 *comment.Doc，再把这个文档交给 comment.Printer.Markdown。这样标题、列表、链接和预格式化文本都由同一套结构负责转换。

先划清三层职责，Markdown 转换就不会乱

这个包把文档注释拆成三层。第一层是输入文本，通常已经去掉了 // 或块注释标记；第二层是 *comment.Doc，其中的 Content 由段落、标题、列表和代码块等结构组成，另外还保存链接定义；第三层是 Printer，它根据目标格式把 Doc 重新排版。

因此，Printer.Markdown 不是“把任意字符串变成 Markdown”的清洗函数。它接收的是解析后的 *comment.Doc，返回的是新的字节切片。要是输入还停留在原始注释层，就先补上 Parser.Parse：

用 Parser.Parse 和 Printer.Markdown 组成最小工作流

下面的函数把一段已经移除注释标记的文档文本转换为 Markdown。示例重点是数据边界：解析器产出 *comment.Doc，打印器产出 []byte，文件写入只发生在转换完成之后。

package main

import (
	"fmt"
	"os"

	"go/doc/comment"
)

func commentToMarkdown(text string) ([]byte, error) {
	var parser comment.Parser
	doc := parser.Parse(text)
	if doc == nil {
		// 解析结果为空时返回明确错误，避免把空文档当成成功输出。
		return nil, fmt.Errorf("parse doc comment: empty document")
	}

	var printer comment.Printer
	// Markdown 会保留文档结构，并返回可直接写出的字节内容。
	return printer.Markdown(doc), nil
}

func main() {
	input := "# 使用说明\\n\\n把链接写进文档。"
	markdown, err := commentToMarkdown(input)
	if err != nil {
		// 转换失败时先报告错误，不继续写入不完整文件。
		fmt.Fprintln(os.Stderr, err)
		return
	}

	if err := os.WriteFile("README.md", markdown, 0o644); err != nil {
		// 文件写入错误要向调用方返回，而不是静默丢失结果。
		fmt.Fprintln(os.Stderr, err)
	}
}

这里的 Parse 接收的是文档内容，不负责读取 Go 源文件本身。如果你的工具从 AST 或源码文件出发，还需要在更外层完成注释提取；进入本函数后，任务已经收敛为“结构化文档转 Markdown”。

Markdown 输出的定制点：标题、链接与换行

Printer 的字段可以在调用打印方法前设置。HeadingLevel 控制 HTML 和 Markdown 标题的起始层级，零值默认使用三级标题；HeadingID 为标题计算 ID，返回空字符串时可以省略 ID。文档链接则可以通过 DocLinkURL 自定义，未自定义时会结合 DocLinkBaseURL 生成默认地址。

这几个字段处理的是“输出策略”，不是修改 Doc 的内容。比如你只想让导出的标题从二级开始，可以只调整打印器：

func markdownWithPolicy(text string) ([]byte, error) {
	var parser comment.Parser
	doc := parser.Parse(text)
	if doc == nil {
		// 空文档没有可格式化的结构，调用方应先处理这个边界。
		return nil, fmt.Errorf("empty comment")
	}

	printer := comment.Printer{
		HeadingLevel: 2,
		HeadingID: func(h *comment.Heading) string {
			// 返回空字符串表示不为标题生成锚点 ID。
			return ""
		},
		DocLinkBaseURL: "https://pkg.go.dev/",
	}
	return printer.Markdown(doc), nil
}

如果文档里包含 DocLink，更细粒度的地址策略可以放进 DocLinkURL 回调；如果不需要自定义，就让默认规则根据链接对象和基础地址生成。

不要把 TextWidth 当成 Markdown 的换行开关

Printer 还提供 TextPrefix、TextCodePrefix 和 TextWidth，但它们主要服务于 Text 方法的纯文本输出。TextWidth 的单位是 Unicode code point，零值有默认宽度，负值表示不限制；它不是给 Markdown 设置行宽的通用开关。

因此可以把目标格式拆开判断：

在批量导出时，我会让同一个 *comment.Doc 服务多个输出目标，而不是先输出 Markdown 再用字符串替换去兼容 HTML 或纯文本。这样每种格式都能保留自己的结构规则，也更容易定位标题和链接差异。

一条可复用的注释转 Markdown 路线

1. 先确定输入边界：传入的是已经去掉注释标记的文档文本，还是需要从源码中额外提取。
2. 用 comment.Parser 解析一次，保留 *comment.Doc 作为中间结构。
3. 根据发布渠道设置 HeadingLevel、HeadingID 和链接策略，不在正文里硬编码替换。
4. 用 Printer.Markdown 得到 []byte，写文件或交给后续管线。
5. 如果还要生成 HTML、纯文本或 Go 注释，复用同一个 Doc，分别调用对应方法。

常见误区有三个：把 Printer 当成字符串清洗器；把 TextWidth 误用于 Markdown 自动换行；以及在输出 Markdown 后再用正则修改标题和链接。它们都会让结构信息变得不可见，后续遇到列表、链接定义或代码块时更难维护。

常见问题

Printer.Markdown 返回字符串吗？

返回类型是 []byte。需要字符串时可以显式转换为 string(printer.Markdown(doc))，写文件时则可以直接把字节交给写入函数。

可以跳过 Parser，直接把字符串传给 Markdown 吗？

不可以。Markdown 接收的是 *comment.Doc；原始注释文本要先通过 Parser.Parse 形成结构化文档。

怎么控制标题 ID？

设置 Printer.HeadingID。回调返回空字符串时省略 ID；不设置回调则使用标题的默认 ID 规则。

官方资料：https://pkg.go.dev/go/doc/comment