Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
118 lines (88 sloc) 4.17 KB

生成文档

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

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

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

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

注意,以 BUG(something) 开头第注释会出现在包文档的 Bugs 部分。如果您正寻找这样的例子,您可以看一下 bytes 包的源码和文档页面,它们分别在 https://golang.org/src/bytes/bytes.gohttps://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 包中。

godoc 服务的根目录

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

documentMe.go 的根页面

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

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
You can’t perform that action at this time.