はじめに

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` でローカルサーバーを起動

コードの可読性が向上し、メンテナンスがしやすくなります。
少しずつ中級者くらいにはレベルアップしたいな〜