Go comment.Parser 为什么把缩进段落识别为代码块

go/doc/comment.Parser 会把文档中的缩进文本按代码块规则解释，内容即使是中文说明也可能成为预格式块。它依据文档语法和缩进结构判断，不通过文字是否像Go代码来分类。若这段内容应是普通正文，应去掉额外缩进，并用空行明确分段。

常见场景是自建文档生成器为了排版给第二段加上制表符，结果网页里出现等宽字体和保留换行的区域。此时先检查传入Parse的原始文本，再查看解析后的块类型，比直接调整网页样式更能找到原因。

先看解析输入中的缩进而非网页样式

文档注释支持普通段落与预格式代码块等不同结构。缩进或空白行形成的块，在不属于列表标记等语法的情况下可成为代码块；其中可以放代码，也可以放命令、数据格式或其他需要保留版式的文字。

因此，“这是自然语言”不足以让解析器忽略缩进。如果生成器把所有续行统一加一个tab，或从模板复制了局部缩进，普通说明就可能被改变语义。要观察的是去掉注释标记后的文本，而不是编辑器中注释前的代码层级。

结构说明图表达语法归属，不是解析步骤或运行结果。

用块类型确认解析器的判断

下面直接构造文档文本，第一段与末段不缩进，中间两行使用tab。这样能把输入来源与HTML渲染问题分开讨论。

package main

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

func main() {
    // Parse 接收去掉注释标记的文档文本，缩进本身有语义。
    text := "Read 返回输入内容。\n\n\t这是缩进的说明文字。\n\t它会按预格式文本处理。\n\n下一段正文。\n"
    var parser comment.Parser
    doc := parser.Parse(text)
    for _, block := range doc.Content {
        // 根据结构类型观察段落和代码块，不从 HTML 样式猜测。
        switch b := block.(type) {
        case *comment.Paragraph:
            fmt.Println("普通段落")
        case *comment.Code:
            fmt.Printf("预格式块：%q\n", b.Text)
        default:
            fmt.Printf("其他文档块：%T\n", block)
        }
    }
}

本文未执行示例。按照这组输入的语法，预期中间缩进文字会对应Code块，其余正文对应Paragraph。打印Code.Text时使用%q，是为了让换行、tab等空白在观察时更明显，而非把打印格式当成文档语法。

如果结构里已经出现Code，问题就在解析输入或文档语法层；若结构仍是Paragraph而页面显示异常，才需要继续查看打印器或页面样式。两类问题的修复位置不同。

按正文意图修正空行与缩进

修正之前先决定这一段到底要表达什么。说明文字应与普通正文保持同一级缩进，用空行隔开段落；真正的示例则保留缩进，并在前后放空行，让读者和工具都容易看清边界。

不要对每一行都调用TrimSpace。那会让真实代码示例的内部缩进消失，也可能破坏列表。更合适的做法是在生成模板中修正误加的局部缩进，或只移除确定属于外层容器的公共前缀。

空行帮助表达块边界，但单独增加空行不会把一个明确缩进的预格式段落自动变成正文。相反，想要保持代码块时，也不应只保留花括号而丢掉示例整体的缩进。

让文档生成器保留语义结构

把文本生成、结构解析与页面展示作为不同职责：生成器负责给出合适的空白，Parser产出文档块，Printer负责输出HTML等形式。展示层应尊重Code和Paragraph的区别，而不是把所有块强行渲染为同一种标签。

说明图中的块类型是共享语义；页面主题只负责视觉呈现。

若从Go源码读取注释，可以通过源码解析阶段取得注释组，再将去掉注释标记的文本交给文档解析器。不要把整份带package和函数声明的源码当成文档文本。若直接构造字符串，则由调用方确保它已经是文档内容。

这种处理有利于文档工具、API参考页和静态站点生成器统一结构，但没有必要把普通注释排版问题包装成行业趋势。实际采用时，先固定一组包含正文、示例和列表的模板样例，观察各块类型是否符合自己的写作意图。

常见问题

代码块里可以只有中文而没有Go代码吗？

可以。它是预格式文本块，分类依赖结构，不要求内容能编译。

用Markdown围栏替代缩进是否更稳？

不要把通用Markdown解析器的行为直接套过来。Go文档注释有自己的轻量语法，应按官方文档组织缩进示例。

能否只修改HTML里的pre样式？

这只能改变外观。若原本意图是普通段落，应修正输入结构；若确实需要预格式文本，才在主题中调整合适的显示效果。

官方语法：https://go.dev/doc/comment#code-blocks；接口文档：https://pkg.go.dev/go/doc/comment。