Question

Go 提供了 godoc 工具，允许您浏览您的包文档——前提是您的文件里包含一些额外信息。

我一般建议您应该尝试把所有的都文档化，除了一些比较明显的。简而言之，不要写：这我创建了一个新的 int 变量。最好表明 int 变量的作用！然而，真正优秀的代码通常不需要文档！

在 Go 中写文档的规则相当简单，直接。为了文档化，您需要在声明前写一行或多行以 // 开头的常规注释。这个规定可用于文档化函数，变量，常量，乃至其他包！

另外，您会注意到任何大小包的文档的第一行会出现在 godoc 的包列表中，如 https://golang.org/pkg 一样。这意味着它是应该是很有描述性和完整性。

注意，以 BUG(something) 开头第注释会出现在包文档的 Bugs 部分。如果您正寻找这样的例子，您可以看一下 bytes 包的源码和文档页面，它们分别在 https://golang.org/src/bytes/bytes.go 和 https://golang.org/pkg/bytes/。

最后，所有和顶级声明无关的注释都将从 godoc 实用程序生成的输出中省略。

看一下下面保存在 documentMe.go 中的代码：

// This package is for showcasing the documentation capabilities of Go
// It is a naive package!
package documentMe

// Pie is a global variable
// This is a silly comment!
const Pie = 3.1415912

// The S1() function finds the length of a string
// It iterates over the string using range
func S1(s string) int {
    if s == "" {
        return 0
    }
    n := 0
    for range s {
        n ++
    }
    return n
}

// The F1() function returns the double value of its input integer
// A better function name would have been Double()!
func F1(n int) int {
    return 2 * n
}

根据上一节讨论的，我们需要创建一个 documentMe_test.go 文件来为它开发示例函数。documentMe_test.go 的内容如下：

package documentMe
import (
    "fmt"
)
func ExampleS1() {
    fmt.Println(S1("123456789"))
    fmt.Println(S1(""))
    // Output:
    // 9
    // 0
}

func ExampleF1() {
    fmt.Println(F1(10))
    fmt.Println(F1(2))
    // Output:
    // 1
    // 55
}

为了能够看到 documentMe.go 的文档， 您需要在本机安装这个包，如您在第6章（Go package中不为人知的知识）。这需要在 Unix shell 里执行如下命令：

接下来，您应该如下执行 godoc 工具：

$godoc -http=":8080"

注意，您可以使用任何没被其他进程占用的端口号。如被占用，您将看到类似下面的错误：

$godoc -http=":22"
2018/03/06 21:03:05 ListenAndServe :22: listen tcp :22: bind: permission denied

注意这点后，您将能够使用您喜欢的 web 浏览器来浏览刚被创建的 HTML 文档。这个文档的 URL 是 http://localhost:8080/pkg/。

下面的截屏显示了我们刚启动的 godoc 服务的根目录。您能看到您创建的 documentMe.go 包在其他 Go 包中。

下面的截屏显示了在 documentMe.go 源文件中实现的 documentMe 包的文档的根目录：

同样，下面的截屏更详细的显示了 documentMe.go 包中 S1() 函数的文档，还包含示例代码。这里的示例代码不是动态的，但您能看到源码和它的输出：

执行 go test 命令将产生如下输出，它可能发现我们代码中的潜在问题和错误：

$go test -v documentMe*
=== RUN ExampleS1
--- PASS: ExampleS1 (0.00s)
=== RUN ExampleF1
--- FAIL: ExampleF1 (0.00s)
got:
20
4
want:
1
55
FAIL
FAIL command-line-arguments 0.005s