Go comment.Parser 怎样接入包名与符号查找函数

如果你只调用 comment.Parser.Parse，文档注释仍然可以被拆成段落、列表、代码块和链接定义，但方括号中的 Go 标识符是否应当成为 DocLink，取决于解析器能不能得到包名和符号上下文。最实用的接入方式是：用 LookupPackage 把短包名映射到完整导入路径，用 LookupSym 判断当前包里的顶层符号和接收者方法。

先记住两个返回值的职责：LookupPackage 返回“导入路径 + 是否识别”，LookupSym 只返回“当前包中是否存在”。前者解决跨包链接，后者解决本包链接；两者都返回未命中时，文本会保留为普通内容。

comment.Parser 的两个查找口分别解决什么

go/doc/comment 把文档注释解析成 *comment.Doc。其中 Parser.Words 可以处理普通标识符的斜体或自动链接，而方括号形式的文档链接还需要判断它指向哪个包、哪个符号。

官方 API 对 LookupPackage 的定义是“把包名解析成导入路径”。例如文档中写着 [kit.Parse] 时，解析器会先拿到 kit，再询问回调是否对应 example.com/project/kit。如果写的是带斜杠的完整导入路径，解析器可以直接按合法导入路径处理，回调主要解决短包名、别名和当前工程的 imports 上下文。

LookupSym 的参数是 recv 和 name。顶层常量、函数、类型或变量使用空接收者，例如 LookupSym("", "Parse")；方法引用则传入接收者类型名，例如 LookupSym("Widget", "Render")。这个回调不负责返回 URL，也不负责查外部包，只回答当前包是否存在该符号。

最小写法：为短包名提供导入路径

先处理跨包引用。下面的索引只保留文档生成器真正需要的映射：短包名到导入路径。回调返回 false 时，不要勉强拼接路径；解析器会把这段方括号文本当成普通文本。

package main

import (
	"fmt"
	"go/doc/comment"
)

func main() {
	// 这张表模拟当前包已经扫描到的 imports 别名。
	imports := map[string]string{
		"kit": "example.com/project/kit",
		"fmt": "fmt",
	}

	var parser comment.Parser
	parser.LookupPackage = func(name string) (string, bool) {
		// 只返回已知映射，避免把未知短名误拼成导入路径。
		path, ok := imports[name]
		return path, ok
	}

	doc := parser.Parse("调用 [kit.Parse]，并参考 [fmt.Sprintf]。")
	for _, link := range doc.Content {
		fmt.Printf("%T\\n", link)
	}
}

这里的关键不是把所有包名都写进 map，而是把解析器所在文件的真实 imports 上下文传进去。若 LookupPackage 保持 nil，标准库单段包名仍由内置的 DefaultLookupPackage 识别；像 kit 这样的项目内短名则没有足够信息，通常不会成为文档链接。

再接入当前包的顶层符号和方法

包名解析成功，只能说明“这个链接属于哪个包”；当链接没有包前缀时，解析器会转向 LookupSym。因此本包注释里的 [Parse]、[Widget.Render] 要靠符号表回答。

package main

import (
	"fmt"
	"go/doc/comment"
)

func main() {
	// 空接收者表示顶层符号；带接收者表示方法。
	symbols := map[string]bool{
		"Parse":         true,
		"Widget.Render": true,
	}

	var parser comment.Parser
	parser.LookupSym = func(recv, name string) bool {
		key := name
		if recv != "" {
			key = recv + "." + name
		}
		// 只做存在性判断，URL 和符号类型交给后续生成阶段。
		return symbols[key]
	}

	doc := parser.Parse("使用 [Parse]，再调用 [Widget.Render]。")
	// Doc.Links 只保存显式链接定义，这里先观察解析后的块数量。
	fmt.Printf("blocks=%d link-defs=%d\\n", len(doc.Content), len(doc.Links))
}

工程代码通常会把 symbols 换成 AST 扫描或类型检查得到的索引。回调只在解析期间被调用，返回值应当是稳定的；不要在回调里修改共享符号表，也不要因为一次未命中就发起网络请求。

把两个回调组合成可追踪的 DocLink

实际生成器可以同时配置两个回调，然后遍历 Doc 中的链接节点。要注意，DocLink 的信息包含导入路径、接收者和名称；最终 URL 怎样拼接属于 Printer 或应用层，不是 LookupPackage 的职责。

package main

import (
	"fmt"
	"go/doc/comment"
)

func main() {
	// 这是一个最小的跨包、本包混合索引。
	imports := map[string]string{"kit": "example.com/project/kit"}
	symbols := map[string]bool{"Parse": true, "Widget.Render": true}

	var parser comment.Parser
	parser.LookupPackage = func(name string) (string, bool) {
		// 当前工程只信任扫描到的 imports。
		path, ok := imports[name]
		return path, ok
	}
	parser.LookupSym = func(recv, name string) bool {
		// 用同一套键规则覆盖顶层符号和方法。
		key := name
		if recv != "" {
			key = recv + "." + name
		}
		return symbols[key]
	}

	doc := parser.Parse("[kit.Parse] 与 [Parse]、[Widget.Render]")
	printer := comment.Printer{
		DocLinkURL: func(link *comment.DocLink) string {
			// 这里才拿到 DocLink 的导入路径、接收者和名称。
			fmt.Printf("import=%q recv=%q name=%q\\n", link.ImportPath, link.Recv, link.Name)
			return link.DefaultURL("https://docs.example/")
		},
	}
	// Printer 负责把已经识别的 DocLink 变成目标格式。
	fmt.Println(string(printer.HTML(doc)))
}

判断是否识别成功时，建议观察 DocLink.ImportPath、DocLink.Recv 和 DocLink.Name 三个字段。跨包链接一般有导入路径，本包顶层符号的导入路径为空且接收者也为空，方法链接则会带接收者。

默认行为和容易混淆的边界

还有一个细节：方括号链接需要处在适合被识别的标点、空格或行边界中，紧贴普通标识符时可能被当成普通文本。另一个边界是 LookupPackage 返回 "", true 的特殊用法，它表示这个包名指向当前包；这适合生成器希望保留包名前缀、但最终仍要按本包处理的场景。

什么时候值得接入查找回调

如果工具只把注释转成纯文本，可以不配置这两个回调；如果要生成可点击的 HTML、Markdown 链接或交叉引用，建议在扫描包时就建立两张索引：一张记录 imports 别名，另一张记录当前包的声明和方法。这样解析阶段只做内存查找，生成阶段再统一决定链接地址。

从采用路径看，最小工具可以先只实现 LookupPackage，解决外部包引用；拥有本包 AST 或类型信息后，再实现 LookupSym。不要为了“全部链接化”把未知文本强行当成链接，因为错误的交叉引用比少一个链接更难排查。

速查：两个回调怎样分工

结论可以压缩成一句话：LookupPackage 解决“这个包是谁”，LookupSym 解决“这个名字在当前包里是否存在”，而 Parser.Parse 只负责把注释文本解析成结构。把这三个职责拆开，文档生成器就能在不修改 Go 标准库解析器的前提下接入自己的 imports 和符号表。

相关问题

LookupPackage 返回空路径但 ok 为 true 是什么意思？ 表示该名字被识别为当前包，适合需要保留包名语义但不希望把它当作外部导入路径的生成器。

LookupSym 能不能返回符号的 URL？ 不能，它只有布尔返回值。应在得到 DocLink 后，由 Printer 的链接函数或应用层根据导入路径、接收者和名称生成 URL。

为什么未知的 [Name] 没有出现在 DocLink 里？ 因为当前包查找返回了 false。这是保护机制，避免把普通方括号文本误认为可点击的 Go 符号。

只配置 LookupSym 能识别 fmt.Sprintf 吗？ 不能。fmt.Sprintf 先走包名解析，外部包需要 LookupPackage 或标准库默认识别；LookupSym 只负责没有包前缀的当前包符号。

参考资料

https://pkg.go.dev/go/doc/comment

https://go.dev/src/go/doc/comment/parse.go

https://go.dev/src/go/doc/comment/doc.go