Go comment.Parser 的 Words 空字符串为什么仍会改变排版

comment.Parser.Words 中，键存在而值为空字符串，含义是“把这个标识符词排成斜体”，并非关闭格式化。值为非空字符串时，该字符串作为链接目标；如果希望普通文本中的这个词不受 Words 特殊处理，应从映射中移除键，而不是把值改成空字符串。

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

这个问题容易出现在文档生成器的配置里：我们只想暂时关掉某个术语的链接，于是保留词条，把 URL 清空。链接确实消失了，斜体却仍然存在。理解这件事，需要同时看“键是否存在”和“映射值是什么”。下面用独立示例解释规则，不假定发生过版本语义变更。

把空字符串理解为格式指令

Words 的类型是 map[string]string。键代表要识别的 Go 标识符词，值代表可选链接目标。官方字段说明明确区分两种情况：空字符串只应用斜体，非空字符串生成链接。因而在这个 API 中，空值是有意义的配置。

如果只读取 words["Queue"]，Go 对不存在的键也会返回字符串零值。这只是 map 单值读取的表现，不代表解析器会把“缺键”和“存在但为空”当成同一种设置。配置工具需要区分它们时，应使用双返回值读取。

用同一段文本比较三种映射

下面只用普通段落里的 Queue，避免混入方括号文档链接等语法。输入已经是去掉注释标记的文本，符合 Parser.Parse 的要求；不要把完整源文件直接作为这里的文本。

package main

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

func main() {
    text := "Queue stores pending jobs."
    cases := []struct {
        name string
        words map[string]string
    }{
        {"absent", nil},
        {"italic", map[string]string{"Queue": ""}},
        {"linked", map[string]string{"Queue": "https://example.com/queue"}},
    }
    for _, c := range cases {
        // 每种配置独立解析同一段文本；示例地址仅作链接占位。
        p := comment.Parser{Words: c.words}
        doc := p.Parse(text)
        var printer comment.Printer
        fmt.Printf("%s: %s", c.name, printer.HTML(doc))
    }
}

这三组配置分别表达普通词、斜体词和带目标地址的链接。HTML 输出能明确承载这些格式区别；纯文本输出主要保留可读内容，不适合据此判断浏览器是否会显示斜体。示例中的 example.com 地址仅用于展示配置形状，不是 Go 文档的官方入口。

阅读生成内容时，先确认观察的是哪个 Printer 方法，以及输入文本是否确实包含匹配词。本文示例是供读者使用的原创代码，没有把插图当成本机运行证据。

移除不需要格式化的键

如果用户选择“关闭链接但保留强调”，空字符串正合适。如果选择“恢复普通文字”，就应删除词条。这两个选项最好在配置界面里分开表达，否则把链接输入框留空很容易产生误会。

// 用双返回值保留存在性，不能只判断 URL 是否为空。
target, exists := words["Queue"]
if exists && target == "" {
    fmt.Println("该词条配置为仅斜体")
}

// 恢复普通词语处理时删除键；需在再次 Parse 之前完成。
delete(words, "Queue")

这段代码用于已有 words 映射的配置逻辑，不是独立完整程序。对 nil map 执行 delete 也是允许的。删除映射项只影响后续解析：如果已经保存了之前 Parse 得到的 Doc，需要用新的配置重新解析原文本，才能让新的规则进入结果。已经生成并保存的 HTML 也不会因修改 map 自动更新。

若配置来自共享模板，先复制出本次使用的映射再调整，避免顺手改变其他文档的配置。解析时也不要同时由另一个协程改写同一张 map；让每次解析使用稳定配置更容易维护。

区分词语映射与文档符号链接

Words 用于标识符词的斜体与目标地址映射。LookupPackage 和 LookupSym 则服务于方括号形式的文档链接识别。比如文档里的方括号符号，不能仅靠删掉 Words 里的词条就断言一定恢复普通文字，还要看它是否被其他文档语法识别。

因此，排查这个标题所说的空字符串问题时，建议先把输入缩小为普通段落中的单个标识符词，只改变 Words 三种状态。确认配置含义后，再回到完整注释，分别处理其他语法和链接解析职责。这种取舍适合维护文档渲染器、注释预览与格式迁移工具的人；只阅读生成文档的用户通常不需要接触这些字段。

Words 为 nil 与空 map 有区别吗？

就这张映射提供的词条而言，两者都没有配置任何词，不会主动为 Queue 添加 Words 特殊格式。这不代表其他文档语法被禁用。

空字符串会产生空链接吗？

字段约定是仅斜体，并非生成指向空地址的链接。要取消特殊处理，应删除键。

为什么改成普通文本输出后看不到斜体？

纯文本不承载 HTML 式视觉样式。需要查看格式效果时，应选择相应格式的 Printer 输出，并区分输出文本与渲染后的呈现。

参考：Go comment.Parser 字段说明、Go comment.Printer 输出接口。