Visual Studio Code のデバッグ環境を整えようと思ったけど、それは想定外に簡単にできてしまった。
プラグイン入れて、delve を入れるだけなのだけど、プラグインも、go のコードを開けたらサジェスチョンされるので、考えなくてよかった。
ですので、今日は、ライブラリを作ったりメンテするにあたって、Go のドキュメンテーションについて調べてみました。
コードとドキュメント
Go では簡単にドキュメントができるようで、コードを書くと、勝手にできる。例えば
package cmd
type Employee struct {
Name string
Age int
}
is actual age plus one.
func (c *Employee) GetAge() int {
return c.Age + 1
}
こんなコードを書いておく。サンプルはGitHub GoDocに上げておいた。
そして
godoc -http :3000
みたいな感じにすると、3000 ポートで、ドキュメントが起動する。
よく見ると、こんな感じでドキュメントができている
折角なのでコメントをつけていこう。
// Package cmd will command and control you.
package cmd
// Employee contains Name and Age with several functions.
// You can use it if you like
type Employee struct {
Name string // name of an employee
Age int // actual age of an employee
}
// GetAge enable you to get fake age. This function returns an age which is actual age plus one.
func (c *Employee) GetAge() int {
return c.Age + 1
}
// GetRealAge get the actual age
//
// Deprecated: use GetAge instead
func (c *Employee) GetRealAge() int {
return c.Age
}
パッケージとメソッドにコメントをつけるといい感じになった。すごく単純だが、ほとんどルールがない。パッケージや、type や、関数などの前に、コメントを書くだけだ。Deprecated: とかのルールもあるが、何か特殊な制御がない様子。（今のところ）あと、一行開けると改行と言うシンプルなルールしかない。
Goのドキュメントのいけてるところはサンプルも書きやすいこと。TDD 野郎の私は当然テストから書いているのだが、こんなコードを書いている。
package cmd
import (
"fmt"
. "github.com/onsi/ginkgo"
. "github.com/onsi/gomega"
)
var _ = Describe("Employee", func() {
Context("When I ask them their age", func() {
It("returns their actual age + 1", func() {
emp := Employee{
"Tsuyoshi Ushio",
46,
}
Expect(emp.GetAge()).To(Equal(47))
})
})
})
func ExampleEmployee() {
emp := Employee{
"Tsuyoshi Ushio",
46,
}
fmt.Println(emp.Name)
fmt.Println(emp.GetAge())
// Output:
// Tsuyoshi Ushio
// 47
}
func ExampleEmployee_GetAge() {
emp := Employee{
"Tsuyoshi Ushio",
46,
}
fmt.Println(emp.GetAge())
// Output: 47
}
実行結果
$ ginkgo -v cmd
Running Suite: Cmd Suite
========================
Random Seed: 1502055402
Will run 1 of 1 specs
Employee When I ask them their age
returns their actual age + 1
/Users/ushio/Codes/gosample/src/github.com/TsuyoshiUshio/GoDoc/cmd/employee_test.go:18
•
Ran 1 of 1 Specs in 0.000 seconds
SUCCESS! -- 1 Passed | 0 Failed | 0 Pending | 0 Skipped PASS
Ginkgo ran 1 suite in 2.130144631s
Test Suite Passed
ポイントは、Example 始まるメソッドで、Example + T() とか、Example + F() とか、Example + T_M() とかで初めてメソッドを書くと、関数やメソッドの使い方のサンプルを示せる。これはわかりやすいよね。
!
ちなみに、パッケージに細かいドキュメントを書きたいときもあるだろう。その時は、doc.go と言うファイルを作るといい。
/*
Employee tool for faking your age
Sometimes, you wants to fake your age by any reason. You can do it with this package.
employee get fake age // fake your age
employee get actuall age // actuall age
Now you are ready to fake it.
*/
package cmd
私のサンプルは超しょぼいが、本物は、こんな感じ Source file src/encoding/gob/doc.go
このコードを書いて、ドキュメントを見るとこんな感じ。
まとめ
Go のドキュメントは、ルールが少なくてシンプルですぐ始められそう。これからコード書く時はちゃんとコメントも書こう。次は C# のコメントも調べたいな。じゃあ、筋トレ行ってくる。