godoc(go doc)コマンド についてのまとめ

先程のエントリーでExampleとgo docの関係がいまいちはっきりしなかったので少し調べてみました。


今回はGOPATH以下このようなのようなディレクトリ構成を想定しています。

src/
    sample.com/mylib1/sample.go
                      sample_test.go

※mylib1ディレクトリ以外は省略

またそれぞれのソースコードの内容は以下のとおりです。
sample.com/mylib1/sample.go

package mylib1

// x / y の計算を行います。
func Div(x int, y int) float64 {
    return float64(x) / float64(y)
}

sample.com/mylib1/sample_test.go

package mylib1

import (
    "testing"
    "fmt"
)

func TestDiv(t *testing.T) {
    if x := Div(5, 2); x != 2.5 {
        t.Errorf("Div(%v, %v) = %v, want %v", 5, 2, x, 2.5)
    }
}

func BenchmarkDiv(b *testing.B) {
    for i := 0; i < b.N; i++ {
        Div(5, 2)
    }
}

func ExampleDiv() {
    fmt.Printf("%v", Div(5, 2))
    // Output: 2.5
}

早速GOPATHディレクトリにて以下のコマンドを実行したところ、

$ go doc sample.com/mylib1
PACKAGE DOCUMENTATION

package mylib1
    import "sample.com/mylib1"



FUNCTIONS

func Div(x int, y int) float64
    x / y の計算を行います。

確かに出力はされましたが期待したものとはちょっと違う気がします。Exampleの内容も出力されていませんし。
それではもう一つのgodocコマンドのほうかと調べてみたところ色々オプションありすぎます。
先人たちの記録を見たりしましたがいまいちこれといった回答が見つかりません。(-htmlオプションでリダイレクトなどはありました)
ふと、+TakashiYokoyama氏がローカルサーバーがどうとかこうとか言っていたのを思い出しオプションを見直すと怪しい物がありました。
GOPATHディレクトリで以下のコマンドを実行しhttp://localhost:6060にブラウザでアクセスすると、

$ godoc -http=:6060

でました、見覚えのある画面です。ローカルでみることができるようです。



パッケージの一覧もみることができます。



下にスクロールしていくと、



なんともう載っています!すばらしい!GOPATH以下の内容をドキュメント化してくれているようです。


さらにmylib1をみてみると、



このように生成されています。
func Divの部分をみるとExampleという部分があり、sample_test.goに書いているExampleDivの内容が記載されていることを確認できました。
最初からパッケージのドキュメントを読めばもっと早く気づいたかもしれません。


おまとしてパッケージリスト、Overviewに載せる方法ですが、以下のようにします。


sample.com/mylib1/sample.go

// Package: Golang Cafe で作成した初めてのパッケージです.
// 最初のピリオドまでがパッケージリストに表示され、残りはOverviewに表示されます。
// 
// References:
//   http://golang.jp/
package mylib1

// x / y の計算を行います。
func Div(x int, y int) float64 {
    return float64(x) / float64(y)
}

sample.com/mylib1/sample_test.go

package mylib1

import (
    "testing"
    "fmt"
)

// TestとBenchmarkDivは省略

func Example() {
    // Overviewに載せるExampleコードです。
}

func ExampleDiv() {
    fmt.Printf("%v", Div(5, 2))
    // Output: 2.5
}

パッケージ一覧ではこのように表示されます。



詳細ではこのように表示されます。



さらに補足ですが、パッケージのソースコードを見ると用途(?)ごとにファイルを分けているようです。
bench_test.go
common.go
example_test.go