Go 言語のドキュメント・フレームワーク
（初出： はじめての Go 言語 (on Windows) その8 - Qiita）
前回の続き。 パッケージ化したのならドキュメントを書きましょう。
godoc のインストール
godoc は Go 言語のドキュメント化ツールです。
go get コマンドで導入できます。（go get コマンドについては「go get コマンドでパッケージを管理する」を参照）
ちなみに godoc の実行モジュールは %GOPATH\bin フォルダではなく %GOROOT%\bin フォルダに格納されます。
これで
とかやるとパッケージ（この場合は time パッケージ）のドキュメントが表示されるのですが，さすがにコマンドプロンプトでこれを見るのは辛いので， HTTP サービスを起動します。
これでブラウザで http://localhost:3000/ にアクセスするとドキュメントを見ることができます。
たとえば time パッケージはこんなふうに表示されます。
本家サイトと同じですね。
godoc で modjulian パッケージを見てみる
「機能のパッケージ化」で作った github.com/spiegel-im-spiegel/astrocalc/modjulian はどうなっているでしょう。
全くコメントがないので，さすがに一覧には何もないですが，個別ページには最小限の情報が載っています。凄いなぁ。
modjulian パッケージにドキュメント用のコメントを追記する
では，ソースコードを少しいじってドキュメント用のコードを追記してみましょう。
/**
* Astronomical calculation for Golang.
* These codes are licensed under CC0.
* https://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
}
日本語ですみません。 英語不得手なもので。
- パッケージのコメントは
package指定の直前のコメントが有効になる。（ファイル先頭のコメントは反映されない） - パッケージリストの説明はパッケージ・コメントの最初の1文のみ表示される（日本語の句読点も理解しているらしい）
- 関数等のコメントはそれぞれの記述の直前のコメントが有効になる。
- 基本的に改行は無視される。ただし空行があれば別のパラグラフと理解しているようだ。
- 空白文字2文字のインデントでコード記述領域（HTML 的には
<pre>要素）とみなしているらしい。コードを書く必要はないけど。
上の例では説明のためにコメント内にサンプルコードを載せましたが，サンプルコードを記述するのであればもっとスマートな方法があります。 それはテストにサンプルコードを含める方法です。
package modjulian_test
import (
"fmt"
"time"
"github.com/spiegel-im-spiegel/astrocalc/modjulian"
)
func ExampleDayNumber() {
t := time.Date(2015, 1, 1, 0, 0, 0, 0, time.UTC)
fmt.Print(modjulian.DayNumber(t))
// Output:
// 57023
}
このようなテスト example_test.go を作ると，ドキュメントが以下のようになります。
もちろん，テストもできます。
C:\workspace\jd>go test -v github.com/spiegel-im-spiegel/astrocalc/modjulian
=== RUN TestDayNumber
--- PASS: TestDayNumber (0.00s)
=== RUN ExampleDayNumber
--- PASS: ExampleDayNumber (0.00s)
PASS
ok github.com/spiegel-im-spiegel/astrocalc/modjulian 2.755s
この仕組みを使えばサンプルコードを常に最新の仕様にマッチさせることが可能になります。 プログラマにとってドキュメントで一番欲しいのはサンプルコードなので，サンプルコードさえ正しければ，他はそれほど詳細に書かなくても推測できます。 そういう意味で，このようなテストと連動したドキュメント・フレームワークはなかなかおもしろいと思います。