godocのメモ
golanghttps://godoc.org/golang.org/x/tools/cmd/godoc
コメントからドキュメントを生成する。
$ godoc cmd/fmt Printf
func Printf(format string, a ...interface{}) (n int, err error)
Printf formats according to a format specifier and writes to standard
output. It returns the number of bytes written and any write error
encountered.
$ godoc -src cmd/fmt Printf
// Printf formats according to a format specifier and writes to standard output.
// It returns the number of bytes written and any write error encountered.
func Printf(format string, a ...interface{}) (n int, err error) {
return Fprintf(os.Stdout, format, a...)
}
記述対象の要素の名前から始まる、完全な文としてコメントを書く。
インデントすれば整形した文になり、Bug(ユーザー名):
から始めればバグセクションにまとめられる。
// foo bar package
package foo
import "fmt"
// Hoge returns "HOGE (input num)" string.
// Hoge
// Fuga
// Piyo
// BUG(sambaiz): when passed 2, it panic.
func Hoge(num int) string {
if num == 2 {
panic("AAAAAAAAHHHH")
}
return fuga("HOGE", num)
}
// returns "(keyword) (num)" string
func fuga(keyword string, num int) string {
return fmt.Sprintf("%s %d", keyword, num)
}
例をExampleXXX
のような関数に書いておくと、これもドキュメントに追加される。
package foo
import (
"fmt"
"testing"
)
func TestHoge(t *testing.T){
...
}
func ExampleHoge() {
fmt.Println(Hoge(1))
// Output: HOGE 1
}
Webサーバーを立ち上げてブラウザで確認する。
$ godoc -http=:6060
こんな感じでfooパッケージのドキュメントが表示される。
http://localhost:6060/pkg/github.com/sambaiz/godoctest/foo/