## 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
)
```
- 1. 关于本文
- 2. Go语言简介
- 3. 安装go环境
- 3.1. 简介
- 3.2. 安装C语言工具
- 3.3. 安装Mercurial
- 3.4. 获取代码
- 3.5. 安装Go
- 3.6. 编写程序
- 3.7. 进一步学习
- 3.8. 更新go到新版本
- 3.9. 社区资源
- 3.10. 环境变量
- 4. Go语言入门
- 4.1. 简介
- 4.2. Hello,世界
- 4.3. 分号(Semicolons)
- 4.4. 编译
- 4.5. Echo
- 4.6. 类型简介
- 4.7. 申请内存
- 4.8. 常量
- 4.9. I/O包
- 4.10. Rotting cats
- 4.11. Sorting
- 4.12. 打印输出
- 4.13. 生成素数
- 4.14. Multiplexing
- 5. Effective Go
- 5.1. 简介
- 5.2. 格式化
- 5.3. 注释
- 5.4. 命名
- 5.5. 分号
- 5.6. 控制流
- 5.7. 函数
- 5.8. 数据
- 5.9. 初始化
- 5.10. 方法
- 5.11. 接口和其他类型
- 5.12. 内置
- 5.13. 并发
- 5.14. 错误处理
- 5.15. Web服务器
- 6. 如何编写Go程序
- 6.1. 简介
- 6.2. 社区资源
- 6.3. 新建一个包
- 6.4. 测试
- 6.5. 一个带测试的演示包
- 7. Codelab: 编写Web程序
- 7.1. 简介
- 7.2. 开始
- 7.3. 数据结构
- 7.4. 使用http包
- 7.5. 基于http提供wiki页面
- 7.6. 编辑页面
- 7.7. template包
- 7.8. 处理不存在的页面
- 7.9. 储存页面
- 7.10. 错误处理
- 7.11. 模板缓存
- 7.12. 验证
- 7.13. 函数文本和闭包
- 7.14. 试试!
- 7.15. 其他任务
- 8. 针对C++程序员指南
- 8.1. 概念差异
- 8.2. 语法
- 8.3. 常量
- 8.4. Slices(切片)
- 8.5. 构造值对象
- 8.6. Interfaces(接口)
- 8.7. Goroutines
- 8.8. Channels(管道)
- 9. 内存模型
- 9.1. 简介
- 9.2. Happens Before
- 9.3. 同步(Synchronization)
- 9.4. 错误的同步方式
- 10. 附录
- 10.1. 命令行工具
- 10.2. 视频和讲座
- 10.3. Release History
- 10.4. Go Roadmap
- 10.5. 相关资源