コードとドキュメント

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# のコメントも調べたいな。じゃあ、筋トレ行ってくる。

リソース