首次使用 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/,你就可以看到文档。

godoc

例如,time包的显示如下。

godoc: time package

这个网站和原网站一样。

让我用中文来解释一下,请看 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"
godoc; package list
godoc: modjulian package

由于完全没有评论,所以在概览中真的没有什么内容,但在个别页面中包含了最基本的信息。真厉害。

在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
}
godoc; package list 2
godoc: modjulian package 2

非常抱歉,我不擅长英语,只会说日语。

    1. 包装的注释将在包指定之前的注释生效。(文件开头的注释不会被反映)

 

    1. 包列表的描述只显示包注释的第一句话(似乎也理解了日语的句读点)

 

    1. 函数等的注释将在各自的描述之前生效。

 

    1. 基本上忽略换行符。但是如果有空行,似乎会理解为另一段落。

 

    1. 似乎以两个空格字符的缩进为代码编写区域(在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
}

制作这样的测试时,文档会如下所示。

godoc: modjulian package 3

当然可以进行测试。

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のメモ
广告
将在 10 秒后关闭
bannerAds