Go

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

More than 1 year has passed since last update.

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 ポートで、ドキュメントが起動する。

Screen Shot 2017-08-06 at 13.16.51.png

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

Screen Shot 2017-08-06 at 13.17.19.png

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

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

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() とかで初めてメソッドを書くと、関数やメソッドの使い方のサンプルを示せる。これはわかりやすいよね。
Screen Shot 2017-08-06 at 14.42.26.png

!
ちなみに、パッケージに細かいドキュメントを書きたいときもあるだろう。その時は、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

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

Screen Shot 2017-08-06 at 14.39.42.png

まとめ

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

リソース