go-documentation

Go Documentation

Godoc は自由形式の文章ではなく、ツールチェーンによってレンダリングされる規約です。 この規約に従ったコメントは pkg.go.dev で閲覧できるドキュメントになり、 従わないコメントはノイズになります。

コミュニティのデフォルトです。go-documentation を明示的に置き換えるプロジェクトスキルやエージェント設定ルールがある場合は、そちらを優先します。

詳細なリファレンス資料は必要に応じて読み込みます。

• references/project-docs.md — ライブラリやサービス向けの README テンプレート、CHANGELOG、llms.txt、CONTRIBUTING。

以下の概要だけでは不十分な場合に限り、リファレンスファイルを読んでください。

1. ドキュメントコメントの形式

エクスポートされる識別子にはすべてドキュメントコメントを付けます。コメントは識別子の名前から始め、完全な文にします。

// ✅ Good
// ParseDuration parses a duration string such as "300ms" or "2h45m".
// It returns an error if the string is not a valid duration.
func ParseDuration(s string) (Duration, error) { ... }

// ❌ Bad — doesn't start with the name, fragment, restates signature
// this function parses durations
func ParseDuration(s string) (Duration, error) { ... }

• 関連する定数や変数のグループには、ブロックに対して1つのコメントを共有できます。const (...) グループの上に // Common HTTP methods. と記述します。
• 非エクスポート識別子には、名前から目的が明らかでない場合にコメントを付けます。同じ形式にしますが、必須ではありません。
• 呼び出し元が知る必要のある内容を記述します。動作、エラー条件、nil／ゼロ値の扱い、並行安全性などです。実装の説明は避けます。

2. パッケージのドキュメント

各パッケージには、package 句にパッケージコメントを1つ付けます。数文を超える場合は、専用の doc.go に記述します。

// Package retry implements backoff strategies for retrying failed
// operations.
//
// The zero value of Policy retries three times with exponential
// backoff. Use functional options to customize:
//
//	p := retry.NewPolicy(retry.WithMaxAttempts(5))
//	err := p.Do(ctx, fetchUser)
package retry

• 「Package ...」で始めます。
• インデントされた行（タブ1つ）はコードブロックとしてレンダリングされます。
• main パッケージでは、コマンドとそのフラグについてコメントで説明します。これはコマンドのドキュメントになります。

3. ドキュメントリンクと書式設定（Go 1.19+）

// Fetch retrieves the resource. It honors the deadline of ctx and
// returns [ErrNotFound] if the resource does not exist.
//
// For batch retrieval use [Client.FetchAll]. See the [net/http]
// package for transport configuration.
func (c *Client) Fetch(ctx context.Context, id string) (*Resource, error)

• [Name]、[Type.Method]、[pkg/path] は pkg.go.dev 上でハイパーリンクになります。
• # で始まる行は見出しになります（まれに、長いパッケージドキュメントでのみ使用します）。
• リスト：空白と箇条書き記号で始まる行を使います。階層は浅く保ちます。

4. テスト可能な例

Example 関数は、コンパイラーによってチェックされるドキュメントです。<pkg>_test パッケージの example_test.go に記述します。

func ExampleParseDuration() {
    d, _ := ParseDuration("1h30m")
    fmt.Println(d.Minutes())
    // Output: 90
}

// Method example: ExampleType_Method
func ExamplePolicy_Do() { ... }

// Second example for the same symbol: suffix
func ExampleParseDuration_negative() { ... }

• // Output: コメントを付けるとテストとして扱われます。出力内容が異なると go test は失敗します。このコメントがない Example はコンパイルされますが、実行されません。
• 重要なエクスポート API にはすべて Example を記述します。Example は pkg.go.dev でシンボルの直下に表示されます。

5. 非推奨

// Fetch retrieves the resource.
//
// Deprecated: Use [Client.FetchContext] instead, which honors
// context cancellation.
func (c *Client) Fetch(id string) (*Resource, error)

• 段落は必ず Deprecated: で始めます。
• 代替手段を必ず明記します。
• ツール（gopls、staticcheck、pkg.go.dev）は、これらを自動的に表示します。

6. 書かないこと

// ❌ Noise — restates the code
// GetName returns the name.
func (u *User) GetName() string { return u.name }

// ❌ Maintenance history — belongs in git
// Changed 2024-03-01 by alice: added caching.

// ❌ Commented-out code kept "for reference"

ドキュメントコメントがシグネチャの言い換えにしかならない場合は、コメントでシグネチャからは分からないことを説明できるよう、名前を改善します。または、API 全体がドキュメント化されている場合は、対称性を保つための最小限のコメントを許容します。

7. プロジェクトレベルのドキュメント

• README — ライブラリでは、機能、インストール方法、最小限の実行可能な例、pkg.go.dev へのリンクを先に示し、API の重複を避けます。サービスでは、実行方法、設定表（可能な場合は設定用の構造体から生成）、ヘルスチェック、メトリクス、運用手順書の場所を先に示します。
• CHANGELOG — Keep a Changelog のセクション（Added、Changed、Deprecated、Removed、Fixed、Security）を使います。コミットログではなく、モジュールの利用者向けに記述します。
• llms.txt — ドキュメントのルートに置く短い Markdown インデックスで、AI アシスタントを API リファレンスや例へ案内します。
• Go 1.27+：go doc example.com/[email protected] は go.mod を変更せずに別バージョンのドキュメントを読み込みます。go doc -ex は実行可能な Example の一覧を表示します。

テンプレート：references/project-docs.md。

実行可能な検証

go vet ./...                  # flags some malformed doc comments
gofmt -l .                    # Go 1.19+ gofmt normalizes doc comments
go test ./...                 # runs Example functions with Output
go doc ./mypkg Symbol         # render what users will actually see

閲覧可能なプレビューを表示するには、利用できる場合はローカルの pkgsite を実行します。 go run golang.org/x/pkgsite/cmd/pkgsite@latest を実行し、モジュールを開きます。

検証チェックリスト

1. エクスポートされたすべての識別子に、名前で始まるドキュメントコメントが付いている
2. パッケージコメント（「Package ...」）があり、長い場合は doc.go に記載されている
3. エクスポートされた API のエラー条件と nil／ゼロ値の動作が文書化されている
4. 呼び出し側が誤解する可能性がある箇所では、並行処理の安全性が明記されている
5. 説明文中の単独の名前ではなく、[Symbol] のドキュメントリンクを使用している
6. 自明でないエクスポート済み API に、// Output: を含む Example 関数がある
7. 非推奨の項目では正確な形式の Deprecated: を使用し、代替手段を示している
8. シグネチャの言い換え、履歴の追跡、または使用されていないコードを含むコメントがない
9. go test ./... が Example を有効にした状態で成功する
10. README の冒頭で目的と動作する例を示しており、ユーザーに見える変更について CHANGELOG が更新されている