Go 文檔注釋要改進(jìn)了：十幾年才改一次

大家好，我是 polarisxu。

日前，Go 開發(fā)團(tuán)隊(duì) Leader Russ Cox 發(fā)起一個(gè)討論，關(guān)于 Go 文檔注釋修改的意見和建議。

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

熟悉 Java、PHP 等的小伙伴，對比 Javadoc、PHPDoc，會(huì)覺得 Godoc 功能確實(shí)有點(diǎn)弱。不過 Go 強(qiáng)調(diào)，文檔注釋的主要設(shè)計(jì)標(biāo)準(zhǔn)是使它們在直接查看源代碼時(shí)可以作為普通注釋閱讀，優(yōu)先考慮可讀性，避免語法的繁文縟節(jié)和復(fù)雜性，這是最重要的目標(biāo)。

自 2009 引入 Godoc^[1] 以來，文檔注釋一直沒有太多變化，只在 2011 年增加了標(biāo)題功能^[2]。可能你從來沒有留意文檔中標(biāo)題有什么要求：

• 標(biāo)題前后有空行
• 標(biāo)題必須以大寫字母開頭；以字母、數(shù)字或冒號(hào)結(jié)尾

但標(biāo)題這樣的限制，社區(qū)不少人提出了建議，見 #7349^[3]、#31739^[4]、#34377^[5]。

關(guān)于 Godoc 書寫相關(guān)說明可以參考官方博文：https://docs.studygolang.com/blog/godoc。

Go 語言一個(gè)特別好的地方，就是官方一直保持兼容性。Godoc 同樣有此要求。Russ Cox 強(qiáng)調(diào)，新的修改必須向后兼容，同時(shí)也要適當(dāng)保證向前兼容，即新的文檔注釋在舊的 Go 版本也能較好顯示，實(shí)現(xiàn)平滑過渡。

同時(shí)，這次希望編寫單獨(dú)的如何使用 doc comment 的文檔，而不是包含在 ToHTML^[6] 這個(gè) API 文檔中。

總結(jié)了相關(guān)問題后，Russ Cox 認(rèn)為，這次修改主要解決 5 個(gè)問題：

• 標(biāo)題的語法更容易預(yù)測
• 增加對列表的支持
• 增加對 URL 鏈接的支持（之前雖然能解析 URL，但特殊的 URL 會(huì)解析錯(cuò)誤）
• 增加對 Go API 文檔鏈接的支持
• 將文檔注釋的格式化添加到 gofmt 中，提供外觀的一致性

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

針對很多人提出的其他需求，比如支持圖片、支持 Markdown 語法，Russ Cox 較明確的指出不會(huì)支持，因?yàn)檎Z法簡單是 Godoc 追求的，也是 Go 追求的。不過有些地方會(huì)借鑒 Markdown 的一些特性，比如標(biāo)題，現(xiàn)在限制太多，不容易記憶，會(huì)考慮采用 Markdown 的方式等。

Russ Cox 對其中每一個(gè)問題的可能方案進(jìn)行了詳細(xì)說明，有興趣的可以參與討論：https://github.com/golang/go/discussions/48305。

參考資料