## 5.3\. 注釋 Go支持C語言風格的`/* */`塊注釋，也支持C＋＋風格的`//`行注釋。 當然，行注釋更通用，塊注釋主要用于針對包的詳細說明或者屏蔽大塊的代碼。 程序 - 也是網頁服務器 - godoc 處理 Go 的源代碼，從中提取包的文檔。頂層聲明前的注解，如無空行相隔，和聲明一起提取作為條目的解釋文字。這些注解的性質和風格決定著 godoc 產生的文檔的質量。 每個包都應有一個包注解，即 package 前的塊注解。對多個文件的包，包注解只需出現在一個文件中，隨便哪個。包注解應該介紹此包，并作為一個整體提供此包的對應信息。它首先出現在 godoc 頁面，來安排好后續的詳細文檔 ``` /* The regexp package implements a simple library for regular expressions. The syntax of the regular expressions accepted is: regexp: concatenation { '|' concatenation } concatenation: { closure } closure: term [ '*' | '+' | '?' ] term: '^' '$' '.' character '[' [ '^' ] character-ranges ']' '(' regexp ')' */ package regexp ``` 包如果簡單，注釋可以簡短。 ``` // The path package implements utility routines for // manipulating slash-separated filename paths. ``` 注解不需多余排版如星星橫幅等。生成的結果呈現時可能不是等寬字體，所以不要靠空格對齊， godoc，類似 gofmt 照管這些。最后，注解是不加解釋的文本，HTML和其他例如 _this_ 會原樣照搬，所以應 避免使用。 在包里，緊跟頂層聲明前的注解作為此聲明的文注解，程序中每個導出（大寫）的名字都應該有文注解。 文注解最好是完整的句子。首句應該以聲明的名字開始的一句話的總結。 ``` // Compile parses a regular expression and returns, if successful, a Regexp // object that can be used to match against text. func Compile(str string) (regexp *Regexp, error os.Error) { ``` Go 的聲明句法允許編組。單一的文注解可以引出一組相聯的常量或變量。因為整組聲明一起展現，注解可以很粗略： ``` // Error codes returned by failures to parse an expression. var ( ErrInternal = os.NewError("internal error") ErrUnmatchedLpar = os.NewError("unmatched '('") ErrUnmatchedRpar = os.NewError("unmatched ')'") ... ) ``` 對于私有名稱，編組也可以指出它們之間的聯系，例如一系列的變量由一個互斥保護。 ``` var ( countLock sync.Mutex inputCount uint32 outputCount uint32 errorCount uint32 ) ```