godocのメモ

(2017-04-05)

https://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/

godoc