Go 文档注释要改进了：十几年才改一次

大家好，我是 polarisxu。

日前，Go 开发团队 Leader Russ Cox 发起一个讨论，关于 Go 文档注释修改的意见和建议。

doc comment revisions: headings, lists, and links：https://github.com/golang/go/discussions/48305

熟悉 Java、PHP 等的小伙伴，对比 Javadoc、PHPDoc，会觉得 Godoc 功能确实有点弱。不过 Go 强调，文档注释的主要设计标准是使它们在直接查看源代码时可以作为普通注释阅读，优先考虑可读性，避免语法的繁文缛节和复杂性，这是最重要的目标。

自 2009 引入 Godoc^[1] 以来，文档注释一直没有太多变化，只在 2011 年增加了标题功能^[2]。可能你从来没有留意文档中标题有什么要求：

• 标题前后有空行
• 标题必须以大写字母开头；以字母、数字或冒号结尾

但标题这样的限制，社区不少人提出了建议，见 #7349^[3]、#31739^[4]、#34377^[5]。

关于 Godoc 书写相关说明可以参考官方博文：https://docs.studygolang.com/blog/godoc。

Go 语言一个特别好的地方，就是官方一直保持兼容性。Godoc 同样有此要求。Russ Cox 强调，新的修改必须向后兼容，同时也要适当保证向前兼容，即新的文档注释在旧的 Go 版本也能较好显示，实现平滑过渡。

同时，这次希望编写单独的如何使用 doc comment 的文档，而不是包含在 ToHTML^[6] 这个 API 文档中。

总结了相关问题后，Russ Cox 认为，这次修改主要解决 5 个问题：

• 标题的语法更容易预测
• 增加对列表的支持
• 增加对 URL 链接的支持（之前虽然能解析 URL，但特殊的 URL 会解析错误）
• 增加对 Go API 文档链接的支持
• 将文档注释的格式化添加到 gofmt 中，提供外观的一致性

Go 官方希望这次修改后能够 10 年后不用修改了。

针对很多人提出的其他需求，比如支持图片、支持 Markdown 语法，Russ Cox 较明确的指出不会支持，因为语法简单是 Godoc 追求的，也是 Go 追求的。不过有些地方会借鉴 Markdown 的一些特性，比如标题，现在限制太多，不容易记忆，会考虑采用 Markdown 的方式等。

Russ Cox 对其中每一个问题的可能方案进行了详细说明，有兴趣的可以参与讨论：https://github.com/golang/go/discussions/48305。

参考资料