学习Golang中的内联评论

内联评论

Go忽略了// 右边的文字：

// This entire line is ignored by the compiler.
// fmt.Println("Does NOT print")
fmt.Println("This gets printed!") // This part gets ignored

块状注释

/* 和*/ 之间的所有行都会被忽略：

/*
This is ignored.
This is also ignored.
fmt.Println("This WON'T print!")
*/

Godoc

Go有一个工具可以从Go源代码中自动生成文档：Godoc。

摘自2011年发布的博文：

Godoc解析Go源代码--包括注释--并生成HTML或纯文本形式的文档。

请看一个HTML格式的例子：zip - GoDoc。

Godoc遵循一些简单的惯例。

封装注释

这种类型的注释应该出现在软件包的某个源文件中：

// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort

顶层标识符注释

这是描述一个顶层函数的格式，const,var, 等等：

// 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 {
  ...
}

错误注释

Godoc忽略了大多数不在顶级元素上方的注释。错误注释是一个例外：它将被包含在软件包的文档中的 "错误 "部分：

// BUG(name): The rule Title uses for word boundaries does not handle Unicode punctuation properly.

括号内的文字是可以提供更多关于该错误信息的人的用户名。

弃用说明

变得多余或过时的元素可以在它们的文档注释中标出一段话，以 "废弃的："开头，后面是一些关于废弃的信息。

// ModTime returns the modification time in UTC using the legacy
// ModifiedDate and ModifiedTime fields.
//
// Deprecated: Use Modified instead.
func (h *FileHeader) ModTime() time.Time {
  return msDosTimeToTime(h.ModifiedDate, h.ModifiedTime)
}

---