注释

[TOC]

注释

类型：

• block comment: /* */
• line comment: //

注释方式：

• 要注释的内容前面进行注释
• doc.go：注释的内容比较多

注释规范：

• 段落的标题： 空行{标题}空行。example： https://golang.org/src/encoding/gob/doc.go#L15
• 简短代码例子：前后空行，代码部分缩进控制
• url会自动转化成html链接
• 第一句注释比较重要：
  • 做为概要句子出现在 godoc's package
  • 注释时必须以注释的对象（比如函数，变量）为开头。例子：https://golang.org/pkg/regexp/#Compile，解释Compile的注释，以Compile开头。
    的简要介绍部分
• 注释只能使用纯文本，包含复杂语法，比如html，md之类的不支持。
• 注释以整个句子为一个单元，如果用逗号把一个句子分成多行，实际使用go doc查看的时候，是一行，查看时，根据宽度，自动换行显示

常见的注释类型

• 普通注释：函数注释，变量注释，doc.go注释
• 已知BUG注释：https://golang.org/pkg/bytes/#pkg-note-BUG
• Deprecated 注释：
  • Deprecated 搜索结果：https://golang.org/search?q=Deprecated:
  • example：https://golang.org/src/archive/tar/common.go?#L59

文档服务器

参考：go godoc 文档服务器

参考

• https://blog.golang.org/godoc-documenting-go-code
• 注释的代码与渲染的例子，对比两个文档查看效果：
  • 代码： https://golang.org/src/encoding/gob/doc.go
  • 渲染后的内容：https://golang.org/pkg/encoding/gob/