go-doc-tips

Go doc tips

1. 新建doc.go作为文档文件，package pkgname之前的注释作为文档。

2. 文档注释的格式

   1. 相邻的行位于同一段落，分段需要添加空行
   2. 上下空行的短语会被作为接下来段落的head
   3. 预先格式化的文本需要跟周围的注释保持缩进
   4. URL会被转换成链接，不需要标记

3. Go同一个目录可以添加{pkg}_test的测试包。

4. 包{pkg}_test的文件(_test.go结尾)，函数名以Example开头且没有参数的函数作为示例代码。

   func ExampleFoo()     // documents the Foo function or type
   func ExampleBar_Qux() // documents the Qux method of type Bar
   func Example()        // documents the package as a whole
   func ExampleReverse() // Reverse first example
   func ExampleReverse_second() // Reverse second example
   func ExampleReverse_third() // Reverse thirdß example

   _test.go结尾的文件，如果只包含一个Example函数，并且有其他包级声明，整个文件会作为示例代码显示。

5. // Output: olleh预期输出，示例函数可以作为go test的测试用例。

   package stringutil_test
   
   import (
       "fmt"
   
       "github.com/golang/example/stringutil"
   )
   
   func ExampleReverse() {
       fmt.Println(stringutil.Reverse("hello"))
       // Output: olleh
   }

打赏