はじめに
GoDoc は、Go 言語のコードにコメントを追加することで、自動的にドキュメントを生成するツールです。
公式の Go パッケージのドキュメントはすべて GoDoc を使って生成されています。
GoDoc とは？
GoDoc は、以下の特徴を持つドキュメント生成ツールです。
- コードのコメント をもとに、自動的にドキュメントを生成する。
- 関数、構造体、インターフェース、パッケージの説明を Markdown 形式で記述可能。
- HTML ページとして出力し、Web ブラウザで確認できる。
GoDoc のメリット
- コードの変更に合わせてドキュメントを自動更新できる。
- コードリーディングの際に、関数や構造体の意図を理解しやすくなる。
- HTML ドキュメントとして公開できる。
GoDoc の基本ルール
1. コメントの記述ルール
- 関数、構造体、インターフェース、パッケージの上にコメントを記述する。
- コメントは
//で始め、対象の名前から始める。
// Add は、2つの整数を加算して返します。
func Add(a int, b int) int {
return a + b
}
2. パッケージコメント
- パッケージの先頭に、そのパッケージ全体の説明を書く。
// Package calculator は、簡単な計算機能を提供します。
package calculator
3. 関数コメント
- 関数の説明には、関数名から始める。
// Subtract は、2つの整数を減算して返します。
func Subtract(a int, b int) int {
return a - b
}
4. 構造体コメント
- 構造体の説明には、構造体名から始める。
// User は、ユーザー情報を表す構造体です。
type User struct {
Name string // ユーザーの名前
Age int // ユーザーの年齢
}
実際に GoDoc を使ってみよう
1. GoDoc のインストール
Go の最新バージョンでは、godoc コマンドは標準で含まれています。
もしインストールされていない場合は、以下のコマンドでインストールできます。
go install golang.org/x/tools/cmd/godoc@latest
2. GoDoc の確認
ターミナルで以下のコマンドを実行することで、ローカルサーバーを起動し、GoDoc を確認できます。
godoc -http=:6060
Web ブラウザで以下の URL にアクセスしてください。
http://localhost:6060
-
localhost:6060にアクセスすると、$GOPATH以下にあるパッケージのドキュメントを確認できます。
3. コード例：GoDoc の書き方と生成
calculator.go
// Package calculator は、基本的な計算機能を提供します。
package calculator
// Add は、2つの整数を加算して返します。
func Add(a int, b int) int {
return a + b
}
// Subtract は、2つの整数を減算して返します。
func Subtract(a int, b int) int {
return a - b
}
以下のコマンドを実行すると、ターミナル上にドキュメントを確認できます。
godoc calculator Add
HTML ドキュメントの生成
godoc を使って、HTML ドキュメントを生成することも可能です。
godoc -html calculator > doc.html
-
doc.htmlが生成され、ブラウザで開くことで、HTML ドキュメントとして確認できます。
まとめ
| 概念 | 説明 |
|---|---|
| GoDoc | コメントから自動でドキュメントを生成するツール |
| 記述ルール | 関数・構造体の上にコメントを書く。対象の名前から始める。 |
| 確認方法 |
godoc -http=:6060 でローカルサーバーを起動 |
コードの可読性が向上し、メンテナンスがしやすくなります。
少しずつ中級者くらいにはレベルアップしたいな〜