Go のドキュメンテーション

Visual Studio Code のデバッグ環境を整えようと思ったけど、それは想定外に簡単にできてしまった。

* [Go programming in VS Code](https://code.visualstudio.com/docs/languages/go)
* [Debugging Go code using VS Code](https://github.com/Microsoft/vscode-go/wiki/Debugging-Go-code-using-VS-Code)
* [delve](https://github.com/derekparker/delve/blob/master/Documentation/installation/osx/install.md)

プラグイン入れて、delve を入れるだけなのだけど、プラグインも、go のコードを開けたらサジェスチョンされるので、考えなくてよかった。

　ですので、今日は、ライブラリを作ったりメンテするにあたって、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](https://github.com/TsuyoshiUshio/GoDoc)に上げておいた。

そして

```
godoc -http :3000
```
みたいな感じにすると、3000 ポートで、ドキュメントが起動する。

![Screen Shot 2017-08-06 at 13.16.51.png](https://qiita-image-store.s3.amazonaws.com/0/3470/ad1e9754-e84c-a65b-238d-c8d2e9e544e8.png)

よく見ると、こんな感じでドキュメントができている

![Screen Shot 2017-08-06 at 13.17.19.png](https://qiita-image-store.s3.amazonaws.com/0/3470/ff6d0cb2-1359-9695-52a2-f151f496f3ad.png)

折角なのでコメントをつけていこう。

```go
// 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:` とかのルールもあるが、何か特殊な制御がない様子。（今のところ）あと、一行開けると改行と言うシンプルなルールしかない。

![Screen Shot 2017-08-06 at 13.28.52.png](https://qiita-image-store.s3.amazonaws.com/0/3470/fce4ab00-5aa5-b535-c52f-a7c65632db0a.png)


* [Godoc: documenting Go code](https://blog.golang.org/godoc-documenting-go-code)
* [Command godoc](http://godoc.org/golang.org/x/tools/cmd/godoc)

Goのドキュメントのいけてるところはサンプルも書きやすいこと。TDD 野郎の私は当然テストから書いているのだが、こんなコードを書いている。

```go
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() とかで初めてメソッドを書くと、関数やメソッドの使い方のサンプルを示せる。これはわかりやすいよね。
![Screen Shot 2017-08-06 at 14.42.26.png](https://qiita-image-store.s3.amazonaws.com/0/3470/db8b2350-605c-0bc1-5b02-4bc7903d9e5f.png)


!
ちなみに、パッケージに細かいドキュメントを書きたいときもあるだろう。その時は、`doc.go` と言うファイルを作るといい。

```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](https://golang.org/src/encoding/gob/doc.go)

このコードを書いて、ドキュメントを見るとこんな感じ。

![Screen Shot 2017-08-06 at 14.39.42.png](https://qiita-image-store.s3.amazonaws.com/0/3470/78a4d41f-364f-d32f-29a0-7bb900b8ae9a.png)

# まとめ

Go のドキュメントは、ルールが少なくてシンプルですぐ始められそう。これからコード書く時はちゃんとコメントも書こう。次は C# のコメントも調べたいな。じゃあ、筋トレ行ってくる。

## リソース

* [Go programming in VS Code](https://code.visualstudio.com/docs/languages/go)
* [Debugging Go code using VS Code](https://github.com/Microsoft/vscode-go/wiki/Debugging-Go-code-using-VS-Code)
* [delve](https://github.com/derekparker/delve/blob/master/Documentation/installation/osx/install.md)
* [Godoc: documenting Go code](https://blog.golang.org/godoc-documenting-go-code)
* [Command godoc](http://godoc.org/golang.org/x/tools/cmd/godoc)
* [Source file src/encoding/gob/doc.go](https://golang.org/src/encoding/gob/doc.go)