Skip to content
This repository was archived by the owner on Aug 24, 2022. It is now read-only.

Rules of godoc documenting

Jump to bottom
YU HengChun edited this page Mar 9, 2015 · 8 revisions

基本规则

Go 团队给出一种在 .go 源码中书写文档的方法. 其基本规则很简单

  1. 代码上方一段无空行间隔的注释被提取到文档.
  2. 行尾注释被原样提取到文档
  3. 其它被文档忽略.
package demo

// 这句注释不会被提取到文档

// 这是 MyFunc 的注释文档
func MyFunc() {
    // 函数主体代码不会被提取
}

type MyType struct {
    // 此行注释属于 Name 的注释, 当然被提取
    Name string // 导出定义的尾注释被原样提取
}

工具

Go 团队提供了一些 package 对文档进行支持.

  1. go/doc 访问 Go AST 中的文档以及 ToHTML, ToText, Note.
  2. tools/godoc 更多的文档支持功能, 未来会被拆分.
  3. cmd/godoc 命令行工具, 生成 (渲染) 文档到其它格式.

渲染

基本规则没有约定渲染后的样子, 上述工具的行为成为事实上的标准. 这里列举一些已知规则:

  1. 按 .go 文件名排序后的顺序提取注释文档.
  2. 所有 package name 语句的注释会被提前合并到文档前部.
  3. 块声明在文档中仍呈现块状.
  4. 注释中的空行, 缩进和首字母大写影响渲染结果

段落与换行

由源码中的空行分割的文本块形成段落. 段落中的空行被保留

源码中的非空行换行只是为了便于阅读, 空行注释是段落中的换行. 示例:

// 第一个段落, 虽然只有一行

// 上面有空行, 形成第二个段落.
// 这个换行会被重新整理, 合并到前行尾部.
//
// 上面有个空行注释, 它会被保留. 这四行属于一个段落.

/*
单行块注释, 这是第三个段落
*/

/*
多行块注释, 这是第四个段落
这个换行会被重新整理, 合并到前行尾部.

上面有个空行注释, 它会被保留. 这四行属于一个段落.
*/

/*
这里展示单行(独立行)注释.

这是个单行注释. 只有一行, 上下都有空行注释.

后续注释...
*/

缩进

缩进是指段落行首有空格或者 \t. 首行注释缩进量被认为是作者书写习惯, 段落被重新整理, 逐行剔除这个缩进量. 整理后, 段落中的连续缩进行( 肯定不包括第一行)被原格式保留(不受行宽限制). 示例:

//        单行的前缩进会被剔除, 因为单行也就是首行.

//    多行的首行前缩进会当作习惯缩进量, 段落被重整.
//         来一行再次缩进的
//    来一行同缩进量的

上面的写法整理后和下面写法是一样效果

// 单行的前缩进会被剔除, 因为单行也就是首行.

// 多行的首行前缩进会当作习惯缩进量, 段落被重整.
//      来一行再次缩进的
// 来一行同缩进量的

行宽限制

段落内的一行限制在 80 个字符, 未超出会合并后续文本, 超出会被加入换行.

单行首字大写

段落中单行注释中首字大写会被区别显示, 在 HTML 中以 <h3> 标签包裹. 示例:

// Nop, 虽然这行首字大写, 但这是首行, 不属于单行注释.
//
// Yes, HTML 中此行会被 h3 包裹.
//
// Nop, 上一行已经被区别显示了, 此行虽然首字大写,但是不会被 h3 包裹.

保留换行代码

有时候因习惯或者代码过长, 作者会手工加入换行, 这些换行被保留. 示例:

func (f HandlerFunc) ServeHTTP(w http.ResponseWriter,
    r *http.Request) { // 这个换行是合法的, 并被保留
}

Synopsis

Synopsis 方法返回一段文本的第一句话, 这就是概要(或者叫简介). 如果文本以 IllegalPrefixes 中的字符串开头, 返回 "". 这对文档生成非常有用, 也需要写文档时注意 IllegalPrefixes 中的字符串有特殊含义. go 中的一句话包简介就是这么来的.

Clone this wiki locally