GoDoc的使用

一. 约定

1. 注释符 // 后面要加空格, 例如: // xxx

2. 在 package, const, type, func 等 关键字 上面并且紧邻关键字的注释才会被展示

   // 此行注释被省略
   
   // 此行注释被展示 
   // 
   // 此行注释被展示2 
   package banana

3. type, const, func 以名称为注释的开头, package 以 Package name 为注释的开头

   // Package banana ...
   package banana
   
   // Xyz ...
   const Xyz = 1
   
   // Abc ...
   type Abc struct {}
   
   // Bcd ...
   func Bcd() {}

4. 有效的关键字注释不应该超过 3 行

   // Package banana ...
   // ...
   // ...
   // 最好不要超过三行
   package banana

5. Package 的注释如果超过 3 行, 应该放在当前包目录下一个单独的文件中, 如: doc.go

6. 如果当前包目录下包含多个 Package 注释的 go 文件(包括 doc.go ), 那么按照 文件名的字母数序 优先显示

   //----- doc.go -----
   
   /*
   ...第一个显示
   */
   package banana

   //----- e.go -----
   
   // Package banana ...第二个显示
   package banana

   //----- f.go -----
   
   // Package banana ...第三个显示
   package banana

7. Package 的注释会出现在godoc的 包列表 中, 但只能展示大约523字节的长度

8. 在无效注释中以 BUG(who) 开头的注释, 将被识别为已知bug, 显示在 bugs 区域, 示例

   // BUG(who): 我是bug说明
   
   // Package banana ...
   package banana

9. 如果 bug注释 和 关键字注释 中间无换行, 那么 混合的注释 将被显示在 bugs 和 godoc列表 两个区域内

   // BUG(who): 我是bug注释
   // Package banana ...也是pkg注释
   package banana

10. 段落:

    /*
    abc ... bcd
    
    Basic(字体加粗变蓝需首字母大写, 中文加粗变蓝需要加上一个大写字母)
    
    abc
    ...
    ... 属于Basic的段落
    ...
    bcd
    */
    package banana

11. 预格式化:

    /*
    abc ... bcd
    
    Abc(不会加粗变蓝, 预格式化和段落不能同时存在)
    
        abc ... 预格式化需要缩进 ... bcd
    */

12. URL将被转化为HTML链接

二. Example

• 文件必须放在当前包下
• 文件名以 example 开头, _ 连接, test 结尾, 如: example_xxx_test.go
• 包名是 当前包名 + _test , 如: strings_test
• 函数名称的格式 func Example[FuncName][_tag]()
• 函数注释会展示在页面上
• 函数结尾加上 // Output: 注释, 说明函数返回的值

// 文件必须放在 banana包目录下, 名字必须为example_xxx_test.go

// Package banana_test 为banana包的示例
package banana_test

// 此注释将会被展示在页面上
// 此函数将被展示在OverView区域
func Example() {
    fmt.Println("Hello OverView")
    
    // Output:
    // Hello OverView
}

// 此函数将被展示在OverView区域, 并展示noOutput标签
func Example_noOutput() {
    fmt.Println("Hello OverView")
    // (Output: )非必须, 存在时将会展示输出结果
}

// 此函数将被展示在Function区域
// Peel必须是banana包实现的方法
func ExamplePeel() {
    fmt.Println("Hello Banana")
    
    // Output:
    // Hello Banana
}

// 此函数将被展示在Function区域
// Peel必须是banana包实现的方法, 并展示big标签
func ExamplePeel_big() {
    fmt.Println("Hello Banana")
    
    // Output:
    // Hello Banana
}

三. Command line

开启一个godoc小型server, -play 可以使用 playground 运行 Example 代码

godoc -http=:6060 -play

四. 参考

• Godoc-一个Go代码文档化工具
• godoc技巧与注意事项