Go go/doc/comment.Parser 怎样解析文档注释

我在做 Go 源码分析工具时，最容易混淆的一点是：文档注释不是普通 Markdown，go/doc/comment 也不是一个“把整份源码变成网页”的生成器。真正的入口是 comment.Parser.Parse：先准备已经去掉 // 或 /* */ 标记的注释文本，再把它解析成可遍历的 *comment.Doc。

官方地址：https://pkg.go.dev/go/doc/comment#Parser

如果你的目标是读取段落、标题、列表和链接，做法是“去掉注释标记 → 调用 Parser.Parse → 遍历 Doc.Blocks → 按需交给 Printer”。不要把原始源码注释连同 // 一起传给 Parse，也不要期待它直接返回 HTML。

先把输入边界理清楚

Parser.Parse 的参数是文档注释正文，不包含 Go 的注释定界符。下面这个小场景模拟一个源码分析器已经从 AST 节点取得了注释正文；代码中的中文注释说明了输入和结果，示例本身不代表线上运行截图。

package main

import (
	"fmt"

	"go/doc/comment"
)

func main() {
	// 这里传入的是去掉 // 或 /* */ 后的文档注释正文。
	text := "读取配置文件。\\n\\n# 约束\\n\\n- 路径必须存在。\\n- 内容需要 UTF-8。"

	var parser comment.Parser
	doc := parser.Parse(text)
	// Parse 返回结构化文档，后续可以按 Block 的具体类型处理。
	fmt.Printf("文档块数量：%d\\n", len(doc.Blocks))
	for _, block := range doc.Blocks {
		// 用类型信息确认当前块是段落、标题、列表还是其他节点。
		fmt.Printf("块类型：%T\\n", block)
	}
}

返回值是 *comment.Doc，其中的 Blocks 保存文档块。常见节点包括 Paragraph、Heading、List、Code 和链接相关节点。这里的关键不是把文本重新切行，而是让后续工具面对稳定的结构。

Parser.Parse 返回了什么

排查解析结果时，我通常先只看块类型，再决定是否深入节点内容。这样可以把“注释没有被识别”和“注释被识别但渲染方式不合适”分开。段落适合提取正文，标题可以转成导航，列表适合生成目录，代码块则应保持预格式化文本。

如果工具需要自定义处理，可以在类型分支中只接入自己关心的节点，而不是把整个 Doc 转成字符串后再用正则猜结构。这个选择也保留了链接、标题和列表的语义。

链接识别要不要自定义

Parser 提供了 Words、LookupPackage 和 LookupSym 等配置入口。它们影响类似 [io.Reader] 或当前包符号引用是否被识别成文档链接。源码分析器知道当前包的导入路径和符号表时，再填回调会比“默认全部当普通文字”更有用。

package main

import "go/doc/comment"

func parseWithLookup(text string) *comment.Doc {
	parser := comment.Parser{
		// 将包名映射到导入路径，空路径表示当前包。
		LookupPackage: func(name string) (string, bool) {
			if name == "config" {
				return "example.com/project/config", true
			}
			return "", false
		},
		// 只有符号表确认存在时，才把当前包符号当作文档链接。
		LookupSym: func(recv, name string) bool {
			return recv == "" && name == "Load"
		},
	}
	return parser.Parse(text)
}

这段配置只表达链接识别边界，不负责检查链接目标是否真的能访问。回调返回 false 时，相关词不会因为“看起来像符号”就被强行改成链接。

用 Printer 输出，不要自己拼格式

解析和呈现是两件事。得到 *comment.Doc 后，可以按消费端选择 Printer.Text、Printer.Markdown、Printer.HTML 或 Printer.Comment。例如搜索索引用纯文本，知识库保留 Markdown，网页展示才选择 HTML。

func render(doc *comment.Doc) ([]byte, []byte, []byte) {
	printer := comment.Printer{
		// 让 Markdown 和 HTML 的标题从二级标题开始。
		HeadingLevel: 2,
	}
	// 同一份结构化文档可以按不同目标生成不同文本。
	return printer.Text(doc), printer.Markdown(doc), printer.HTML(doc)
}

需要注意的是，Printer 负责重新格式化已经解析的文档；它不会替你从 Go 源码中寻找声明，也不会替你决定网站的模板、导航和安全策略。

几个容易误判的地方

• 把注释标记一起传入：Parse 的契约要求标记已经移除，源码层面的清理应放在 AST 或注释提取阶段。
• 只验证输出字符串：如果后续要做目录、链接或列表处理，应保留 Doc.Blocks 的结构，不要过早扁平化。
• 把 Parser 当成文档站：Parser 和 Printer 解决语法与格式化，包扫描、模板、链接校验和发布仍然是上层工具的职责。

相关问题

Parser.Parse 能直接解析 // 开头的源码吗？
不能把它当作源码注释清洗器使用；应先去掉注释标记，再传入正文。

为什么要设置 LookupPackage？
当注释引用外部包或当前包符号时，回调可以帮助解析器判断哪些方括号引用具有文档链接语义。

只想给搜索引擎建索引该选哪个 Printer？
通常先选 Printer.Text，保留干净文本；只有消费端确实需要格式时，再选择 Markdown 或 HTML。