首次使用 Go 语言(在 Windows 上)第8篇
过去的文章目录
继上次的内容。如果进行了打包,那就写下文档吧。
安装godoc
godoc是Go语言的文档化工具。可以通过get命令进行安装(有关get命令的详细信息,请参阅”第3节”)。
C:>go get -v golang.org/x/tools/cmd/godoc
Fetching https://golang.org/x/tools/cmd/godoc?go-get=1
Parsing meta tags from https://golang.org/x/tools/cmd/godoc?go-get=1 (status code 200)
get "golang.org/x/tools/cmd/godoc": found meta tag main.metaImport{Prefix:"golang.org/x/tools", VCS:"git", RepoRoot:"https://go.googlesource.com/tools"} at https://golang.org/x/tools/cmd/godoc?go-get=1
get "golang.org/x/tools/cmd/godoc": verifying non-authoritative meta tag
Fetching https://golang.org/x/tools?go-get=1
Parsing meta tags from https://golang.org/x/tools?go-get=1 (status code 200)
golang.org/x/tools (download)
golang.org/x/tools/blog/atom
golang.org/x/tools/present
golang.org/x/tools/go/ast/astutil
golang.org/x/tools/go/exact
golang.org/x/tools/go/buildutil
golang.org/x/tools/go/types
golang.org/x/tools/container/intsets
golang.org/x/tools/godoc/vfs
golang.org/x/tools/godoc/util
golang.org/x/tools/godoc/vfs/httpfs
golang.org/x/tools/blog
golang.org/x/tools/godoc/redirect
golang.org/x/tools/godoc/static
golang.org/x/tools/godoc/vfs/gatefs
golang.org/x/tools/godoc/vfs/mapfs
golang.org/x/tools/godoc/vfs/zipfs
golang.org/x/tools/playground
golang.org/x/tools/go/types/typeutil
golang.org/x/tools/go/loader
golang.org/x/tools/go/ssa
golang.org/x/tools/go/callgraph
golang.org/x/tools/go/ssa/ssautil
golang.org/x/tools/go/pointer
golang.org/x/tools/godoc/analysis
golang.org/x/tools/godoc
golang.org/x/tools/cmd/godoc
顺便说一下,godoc.exe 实行模块会被存放在 %GOROOT%\bin 文件夹中,而不是 %GOPATH\bin 文件夹中。这样一来
C:>godoc time
一旦执行这个命令(此例中为time包),会显示出包的文档。但在命令提示符下查看这些文档确实很痛苦,因此我将启动HTTP服务。
C:>godoc -http=":3000"
当你在浏览器中访问 http://localhost:3000/,你就可以看到文档。

例如,time包的显示如下。

这个网站和原网站一样。
让我用中文来解释一下,请看 modjulian 包的 godoc。
我们将获取在“第6节”中创建的modjulian包,并在godoc上查看它。
C:>go get -v github.com/spiegel-im-spiegel/astrocalc/modjulian
github.com/spiegel-im-spiegel/astrocalc (download)
github.com/spiegel-im-spiegel/astrocalc/modjulian
C:>godoc -http=":3000"


由于完全没有评论,所以在概览中真的没有什么内容,但在个别页面中包含了最基本的信息。真厉害。
在modjulian包中,添加用于文档的注释。
那么,我们稍微修改源代码,然后添加一些用于文档的代码吧。
/**
* Astronomical calculation for Golang.
* These codes are licensed under CC0.
* http://creativecommons.org/publicdomain/zero/1.0/deed.ja
*/
// modjulian パッケージは
// 修正ユリウス日(Modified Julian Date)の計算を行います。
package modjulian
import "time"
// DayNumber は
// 日付から修正ユリウス通日を取得します。
//
// t := time.Date(2015, 1, 1, 0, 0, 0, 0, time.UTC)
// fmt.Print(modjulian.DayNumber(t)) //57023
//
// 時刻(時分秒)は無視します。
// 1970年1月1日以前のグレゴリオ暦では Fliegel の公式を使って計算します。
// 1970年1月1日以降は UNIX Time を用いて通日を取得します。
func DayNumber(t time.Time) int64 {
if t.Sub(time.Unix(0, 0)) >= 0 {
return dnUnix(t)
} else {
return dnGregorian(t)
}
}
// dnGregorian は
// Fliegel の公式を使い,日付から修正ユリウス通日を計算します。
//
// 時刻(時分秒)は無視します。
func dnGregorian(t time.Time) int64 {
y := int64(t.Year())
m := int64(t.Month())
if m < 3 {
y -= 1
m += 9
} else {
m -= 3
}
d := int64(t.Day()) - 1
return (1461*y)/4 + y/400 - y/100 + (153*m+2)/5 + d - 678881
}
// dnUnix は
// UNIX Time で1970年1月1日からの通日を取得し,修正ユリウス通日を計算します。
//
// 時刻(時分秒)は無視します。
// 1970年1月1日以前の日付では正しく計算できません。
func dnUnix(t time.Time) int64 {
const (
onday = int64(86400) //seconds
baseDay = int64(40587) //Modified Julian Date at January 1, 1970
)
return (t.Unix())/onday + baseDay
}


非常抱歉,我不擅长英语,只会说日语。
-
- 包装的注释将在包指定之前的注释生效。(文件开头的注释不会被反映)
-
- 包列表的描述只显示包注释的第一句话(似乎也理解了日语的句读点)
-
- 函数等的注释将在各自的描述之前生效。
-
- 基本上忽略换行符。但是如果有空行,似乎会理解为另一段落。
-
- 似乎以两个空格字符的缩进为代码编写区域(在HTML中是
元素)。虽然不需要编写代码。
在上面的例子中,为了解释目的,我在评论中附上了示例代码,但是如果要编写示例代码,还有更聪明的方法。那就是将示例代码包含在测试中。
package modjulian_test
import (
"fmt"
"github.com/spiegel-im-spiegel/astrocalc/modjulian"
"time"
)
func ExampleDayNumber() {
t := time.Date(2015, 1, 1, 0, 0, 0, 0, time.UTC)
fmt.Print(modjulian.DayNumber(t))
// Output:
// 57023
}
制作这样的测试时,文档会如下所示。

当然可以进行测试。
C:>go test -v ./...
=== RUN TestDayNumber
--- PASS: TestDayNumber (0.00s)
=== RUN: ExampleDayNumber
--- PASS: ExampleDayNumber (0.00s)
PASS
ok github.com/spiegel-im-spiegel/astrocalc/modjulian 2.038s
如果使用这个机制,可以始终使示例代码与最新的规范相匹配。对于程序员来说,最想要的就是示例代码,因此只要示例代码正确,其他内容就不需要写得太详细,也可以通过推测了解。从这个意义上说,我认为这个文档系统非常有趣。
书签
-
- Go で godoc を使えるようにする〜godoc のインストール〜 – Qiita
-
- Go言語のコードレビュー | SOTA
-
- Go コードのレビュー時によくされるコメント – build error
-
- testingパッケージのExamplesについて – taknb2nchのメモ
-
- GoのExampleテストが便利 : swdyh
- godoc.org への掲載方法を調べた – taknb2nchのメモ