Go 文档注释为什么有些文本会被识别成标题

你在生成 Go 文档或调用 go/doc/comment 时，可能会发现一行普通文字突然被输出成了标题。通常不是渲染器“猜错了”，而是这行文本满足了 Go 文档注释的标题语法，或者它来自 Go 1.19 以前的旧式隐式标题规则。

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

当前最稳妥的判断方式是：显式标题必须以 # 开头，不能缩进，并且要和相邻段落之间有空行；普通段落则是一段未缩进、非空的连续文本。旧代码还可能因为“单行、无结束标点”等条件，被 gofmt 改写成带 # 的形式。

看到意外标题时，先检查行首是不是“井号加空格”和前后空行，再检查是否是 Go 1.19 前的旧式单行段落。要表达普通文字，给句子加句号或冒号，或者主动拆成两行。

解析器先看 # 空格和空行边界

go/doc/comment 不是把文档注释当成一整块纯文本。Parser.Parse 会把内容拆成多个块，块的类型包括 *comment.Heading、*comment.Paragraph、列表和代码块。

当前语法中，标题的关键条件有三个：行首是 U+0023，也就是 #；后面紧跟一个空格；这一行不缩进，并且与相邻段落用空行隔开。少一个空格的 #This 不算标题，缩进的 # This 也不会按普通标题处理。

package main

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

func main() {
	text := "Package demo.\n\n# Options\n\nUse the default file."

	var parser comment.Parser
	doc := parser.Parse(text)
	for index, block := range doc.Content {
		// 类型分支只判断解析出的块，不猜测原始文本的视觉样式。
		switch block.(type) {
		case *comment.Heading:
			fmt.Printf("%d: Heading\\n", index)
		case *comment.Paragraph:
			fmt.Printf("%d: Paragraph\\n", index)
		default:
			// 列表和代码块也属于合法的文档块，不能误归类为段落。
			fmt.Printf("%d: other block\\n", index)
		}
	}
}

这个判断对应的是解析结果，而不是 HTML 标签。之后调用 comment.Printer 输出 HTML、Markdown 或纯文本时，打印器会根据块类型选择对应格式；因此问题应该在 Parser.Parse 这一层定位。

为什么旧注释在 gofmt 后多出一个 #

如果项目里有较早写下的文档注释，现象可能更隐蔽。Go 1.19 以前，文档工具会把满足特定条件的单行段落隐式当作标题，最重要的条件之一就是没有结束标点。升级工具链或运行 gofmt 后，这种旧格式可能被标准化为显式的 # 标题。

所以你看到的 # 不一定是业务代码最近手动添加的，也可能是格式化器把旧语义写成了更明确的新语法。Go 1.19 起，推荐直接使用显式标题，避免依赖历史推断。

// Package demo reads a configuration file.
//
// Options
//
// The old single-line label may be treated specially by older tools.
package demo

// 用完整句子和结束标点表达普通说明，减少旧规则的歧义。
// Options: the following fields control the decoder.
type Options struct {
	Path string // 配置文件路径，供调用方明确传入。
}

如果 Options 只是普通说明，可以改成 Options: 并继续写解释；如果它确实是章节标题，就直接写成独立的 # Options。不要靠调整空格来“碰运气”，因为缩进还可能改变文本块的含义。

普通段落怎样写才不会被误识别

排查时可以按下面的顺序处理：先把真正的章节名改成显式 # ；再给普通标签补上句号或冒号；如果一句话太长，就拆成两行，让它成为连续的段落文本；最后再运行 gofmt，观察格式化前后的差异。

有一点容易混淆：#This is text 因为缺少空格，不是显式标题；而 # This is text 只有在满足不缩进和空行边界时才会识别为标题。标题语法和 Markdown 很像，但文档注释还会经过 Go 自己的解析和打印流程，不能只按网页编辑器的经验判断。

用 Parser 类型分支确认实际块类型

如果文章生成器、静态分析工具或自定义文档流水线仍然出现误判，可以直接检查 doc.Content。比起在最终 HTML 中搜索

func blockName(block comment.Block) string {
	// 让调用方看到解析器的真实块类型，便于定位标题来源。
	switch block.(type) {
	case *comment.Heading:
		return "heading"
	case *comment.Paragraph:
		return "paragraph"
	case *comment.List:
		return "list"
	case *comment.Code:
		return "code"
	default:
		// 未知实现不应被静默当成普通段落。
		return "other"
	}
}

这段代码适合放在调试日志或转换器的中间层。确认块类型后，再决定是否调整原注释、保留标题，或者修改 Printer 的输出配置。不要在输出阶段把所有块统一替换成段落，否则列表和预格式化代码也会一起失去语义。

结论

Go 文档注释被识别成标题，主要有两条路径：当前显式语法中的 # 加空行边界，以及 Go 1.19 以前的隐式单行标题规则。普通说明应使用完整句子、结束标点或明确换行；文档工具则应通过 comment.Parser 的块类型判断真实语义。

相关问题

• 为什么 #This 没有变成标题？ 因为标题标记后必须有空格。
• 能不能只在 HTML 输出阶段修复？ 可以做显示层兜底，但更推荐在注释源文本和 Parser 结果层解决。
• 运行 gofmt 后标题变化怎么办？ 对比格式化前后内容，把旧式隐式标题改成明确的 # 或带标点的普通段落。