ThinkChat2.0新版上线,更智能更精彩,支持会话、画图、阅读、搜索等,送10W Token,即刻开启你的AI之旅 广告
## 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 ) ```