Go Wiki：注释

每个软件包都应有一个软件包注释。它应紧接软件包中某个文件中的 package 语句。 （它只需要出现在一个文件中。）它应以一个句子开头，该句子以“软件包 packagename”开头，并对软件包功能进行简洁总结。此介绍性句子将用于 godoc 中的所有软件包列表。

后续句子和/或段落可以提供更多详细信息。句子应标点正确。

// Package superman implements methods for saving the world.
//
// Experience has shown that a small number of procedures can prove
// helpful when attempting to save the world.
package superman

几乎每个顶级类型、常量、变量和函数都应有一个注释。bar 的注释应采用“bar 漂浮在山谷和山丘的高空。”的形式。bar 的首字母不应该大写，除非它在代码中大写。

// enterOrbit causes Superman to fly into low Earth orbit, a position
// that presents several possibilities for planet salvation.
func enterOrbit() os.Error {
  ...
}

godoc 将在注释中缩进的所有文本呈现为预格式化块。这有助于代码示例。

// fight can be used on any enemy and returns whether Superman won.
//
// Examples:
//
//  fight("a random potato")
//  fight(LexLuthor{})
//
func fight(enemy interface{}) bool {
  ...
}

此内容是 Go Wiki 的一部分。