Go comment.Printer 的 TextWidth 为什么不影响 HTML 输出

调用 go/doc/comment 生成文档时，常见一个容易误判的现象：给 comment.Printer 设置了 TextWidth，纯文本输出会换行，但 HTML 输出看起来完全没有变化。这不是字段失效，而是两种输出走了不同的排版职责。

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

TextWidth 只约束 Printer.Text 生成的纯文本行宽，按 Unicode code point 计算；Printer.HTML 根据 Doc 中的段落、标题和代码块直接生成 HTML 元素，不读取这个宽度设置。需要控制网页显示宽度时，应交给 HTML 模板或 CSS。

先看 TextWidth 到底约束了哪一种输出

comment.Printer 同时提供 Text、Markdown 和 HTML 三种输出方法。它们共享同一个解析后的 *comment.Doc，但目标格式不同：纯文本需要在字符流中安排换行，HTML 则需要保留块级语义。

官方定义中，TextWidth 是文本输出的最大行宽，不包含 TextPrefix 和换行符；宽度单位不是字节，而是 Unicode code point。设置为零时使用默认宽度，设置为负数时表示不限制。

package main

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

func main() {
	// 同一个 Doc 分别交给三种 Printer 方法，观察配置的作用域。
	var parser comment.Parser
	doc := parser.Parse("A paragraph with enough words to make wrapping visible.")

	printer := comment.Printer{TextWidth: 24}
	text := printer.Text(doc)
	markdown := printer.Markdown(doc)
	html := printer.HTML(doc)

	// TextWidth 影响 text 的换行，Markdown 和 HTML 仍由各自格式规则决定。
	fmt.Printf("text=%q\\nmarkdown=%q\\nhtml=%q\\n", text, markdown, html)
}

这里不应把输出差异理解成“HTML 忽略了 Printer 配置”。例如 HeadingLevel 会影响 HTML 和 Markdown 的标题层级，DocLinkURL 也会参与链接地址生成；只是 TextWidth 专门服务于文本行布局。

HTML 输出为什么不读取 TextWidth

理解源码时，关键是 Printer.HTML 创建了一个内部的 htmlPrinter，然后遍历 Doc.Content，把每个文档块交给 block 方法。这个分派过程关心块的类型，不关心纯文本行应该在第几个字符折行。

*comment.Paragraph 会形成

func renderHTML(text string) []byte {
	// Parser 先得到结构化 Doc，HTML Printer 再按块类型输出标签。
	var parser comment.Parser
	doc := parser.Parse(text)

	printer := comment.Printer{
		// 标题层级属于 HTML/Markdown 的结构配置，与 TextWidth 无关。
		HeadingLevel: 2,
		TextWidth:    12,
	}
	return printer.HTML(doc)
}

即使把 TextWidth 调得很小，HTML 仍然可能包含一段很长的文本节点。这是预期行为，因为浏览器的自动换行属于 CSS 布局，通常由容器宽度、overflow-wrap、字体和响应式规则共同决定。

用同一份 Doc 对比三种输出方式

如果你的工具要同时生成 README、终端摘要和网页文档，建议把“文档语义”和“目标格式排版”分开。先解析一次，再分别配置 Printer；不要为了让 HTML 看起来窄一点而修改 TextWidth，否则终端摘要可能变得难读。

func printByTarget(doc *comment.Doc, target string) ([]byte, error) {
	// 每种目标格式只设置自己负责的选项，避免把文本宽度带入 HTML。
	printer := comment.Printer{TextWidth: 72}
	switch target {
	case "text":
		return printer.Text(doc), nil
	case "markdown":
		return printer.Markdown(doc), nil
	case "html":
		return printer.HTML(doc), nil
	default:
		// 未知格式直接返回错误，避免静默生成错误文档。
		return nil, fmt.Errorf("unsupported target: %s", target)
	}
}

实际项目里可以让 HTML 模板包裹 printer.HTML(doc) 的结果，再用 CSS 控制阅读宽度。例如把内容放入带有最大宽度和断词策略的容器；这改变的是页面布局，不是 comment.Doc 的语义结构。

几个容易混淆的配置边界

• 想改 HTML 标题大小：使用 HeadingLevel 或下游 CSS，不要调整 TextWidth。
• 想改文档链接：使用 DocLinkURL 或 DocLinkBaseURL，它们和换行宽度是两套配置。
• 想让代码块更窄：HTML 会保留
  语义，是否横向滚动或折行应由 CSS 决定。
• 看到纯文本仍然很长：检查是否把宽度设成了负数，或者把 TextPrefix 误算进了自己的长度判断。

结论

TextWidth 的职责是帮助 Printer.Text 生成可读的纯文本行，它不会成为 HTML 的隐式 CSS。HTML 输出先按 Doc.Content 的块类型生成结构，再把布局交给浏览器；这正是同一份文档可以稳定复用于终端、Markdown 和网页的原因。

相关问题

• TextWidth 的单位是字节吗？不是，官方定义按 Unicode code point 计算，并排除前缀和换行符。
• HTML 怎样控制阅读宽度？在下游模板或 CSS 容器中设置宽度、断词和溢出策略。
• TextWidth 会影响 Markdown 吗？它的主要语义属于纯文本输出；Markdown 的标记结构和换行规则应按 Markdown 输出结果单独处理。