Go言語の自作パッケージに説明をつけてみる その２

その１はこちら

前回は自作パッケージへのgodocのつけ方をしらべたので、今回はそれを元にどんなgodocの書き方ができるのかを調べて見る。

参考：Effective Go -Commentary

改行してみる

まずは、前回のままだとコメントが改行されずに1行で表示されるだけになってしまっているので、好きなところで改行できないかを試して見る。

$ cd $GOPATH/github.com/chooyan/math
$ vi math.go

コメントを // から /* */ に変えてみる。

math.go

/*
 Package math provides simple functions.
 These are sample functions to practice golang.
*/
package math

func Sum(a int, b int) int {
        return a + b
}

$ godoc github.com/chooyan/math
PACKAGE DOCUMENTATION

package math
    import "github.com/chooyan/math"

    Package math provides simple functions. These are sample functions to
    practice golang.

FUNCTIONS

func Abs(i int) int

func Sum(a int, b int) int

あれ、改行が反映されていない。
試しにもう1行改行してみる。

math.go

/*
 Package math provides simple functions.

 These are sample functions to practice golang.
*/
package math
...略

$ godoc github.com/chooyan/math
PACKAGE DOCUMENTATION

package math
    import "github.com/chooyan/math"

    Package math provides simple functions.

    These are sample functions to practice golang.

FUNCTIONS
...略

お、改行された。
その後いろいろ試してみて、どうやら空行を入れたり、1文字でもインデントを下げたりすると改行される様子。

sum.go

/*
 Package math provides simple functions.
  These are sample functions to practice golang.
 list
  -a
  -b
  -c
*/
package math
...略

$ godoc github.com/chooyan/math
PACKAGE DOCUMENTATION

package math
    import "github.com/chooyan/math"

    Package math provides simple functions.

        These are sample functions to practice golang.

    list

        -a
        -b
        -c

FUNCTIONS
...略

分かりづらいけど、まあ慣れてしまえばコード上はインデントと改行だけで綺麗にgodocがかけるので便利そう。

関数にgodocをつけてみる

関数も基本的には同じ。

sum.go

...略
// Sum is a function to sum up given a and b
func Sum(a int, b int) int {
        return a + b
}

$ godoc github.com/chooyan/math

...略
FUNCTIONS

func Abs(i int) int

func Sum(a int, b int) int
    Sum is a function to sum up given a and b

godocをつけると関数の定義情報の下に出てくる。

関数のgodocの書き方は以下が推奨されている。

The first sentence should be a one-sentence summary that starts with the name being declared.
If the name always begins the comment, the output of godoc can usefully be run through grep.

関数名を文章の先頭に持ってくれば、関数名を思い出せなくても関連しそうな単語から関数を見つけることが簡単になる、というわけらしい。

ドキュメントには書いてないけど、これに従っておけば関数名でgrepした時も、関数定義とgodocだけが表示できて良さそう。

これくらい単純だとマメにドキュメント書く気になる気がする。