Go语言学习 五 注释和文档

本文最初发表在我的个人博客，查看原文，获得更好的阅读体验

---

一 注释

Go提供了两种风格的注释：
一种是C风格的块注释/* */，另一种是C++风格的行注释//，一般情况下使用行注释就可以了；块注释更多情况下出现在包的注释上，也可在表达式中或注掉大段代码时使用。

注释不可嵌套，也不能从符文或字符串字面量中开始。

二 go文档生成

godoc命令既是一个程序，又是一个Web服务器。它可以从源代码的注释中提取有关包内容的文档。顶级声明之前出现的注释（没有插入新行）将与声明一起被提取，作为该条目的解释性文档，而且顶级声明之前的任何注释都充当该声明的doc注释。这些注释的类型和风格决定了godoc生成的文档的质量。

每个包都需要提供包注释，即package子句之前的块注释。如果一个包下面有多个源文件，只需要在其中任意一个提供包注释即可。包注释需要从整体上对该包进行介绍，并提供包相关的信息。它将先出现在godoc页最上面，并应为后面的内容建立详细的文档。包中的每一个导出名称（首字母大写）也需要文档注释。

如果一个包的功能很简单，就不需要写很长的块注释，直接写行注释即可。

1 godoc命