Go ドキュメンテーション

利用可能なスクリプト

• scripts/check-docs.sh — ドキュメントコメントが欠けている exported な関数、型、メソッド、定数、パッケージをレポートします。オプションについては bash scripts/check-docs.sh --help を実行してください。

新しいパッケージまたは exported 型のドキュメントコメントを書くときに、すべてのドキュメンテーション規約の完全なリファレンスが必要な場合は assets/doc-template.go を参照してください。

---

ドキュメントコメント

規範的: すべてのトップレベルの exported 名にはドキュメントコメントが必須です。

基本ルール

1. 説明対象のオブジェクト名で始める
2. 名前の前に冠詞（"a", "an", "the"）が続く場合もあります
3. 完全な文を使用する（大文字で始まり、句読点で終わる）

// A Request represents a request to run a command.
type Request struct { ...

// Encode writes the JSON encoding of req to w.
func Encode(w io.Writer, req *Request) { ...

動作が自明でない unexported な型や関数にもドキュメントコメントを付けるべきです。

検証: ドキュメントコメントを追加した後、bash scripts/check-docs.sh を実行して exported シンボルがドキュメント欠けていないか確認してください。進める前にすべてのギャップを修正してください。

---

コメント文

規範的: ドキュメンテーションコメントは完全な文である必要があります。

• 最初の単語を大文字で始め、句読点で終わる
• 例外：識別子で明確な場合は小文字で始められます
• 構造体フィールドの行末コメントはフレーズでも構いません

---

コメント行の長さ

勧告的: 約80文字を目安にしてください。ただし厳密な上限はありません。

句読点に基づいて改行してください。長い URL は分割しないでください。

---

構造体ドキュメンテーション

フィールドをセクションコメントでグループ化します。オプショナルフィールドはデフォルト値を示します：

type Options struct {
    // General setup:
    Name  string
    Group *FooGroup

    // Customization:
    LargeGroupThreshold int // optional; default: 10
}

---

パッケージコメント

規範的: すべてのパッケージは正確に1つのパッケージコメントを持つ必要があります。

// Package math provides basic constants and mathematical functions.
package math

• main パッケージの場合はバイナリ名を使用してください：// The seed_generator command ...
• 長いパッケージコメントの場合は doc.go ファイルを使用してください

パッケージレベルのドキュメント、main パッケージコメント、doc.go ファイル、または実行可能な例を書くときは references/EXAMPLES.md を参照してください。

---

ドキュメント化するもの

勧告的: 自明でない動作をドキュメント化し、自明な動作はスキップしてください。

トピック	ドキュメント化する場合...	スキップする場合...
パラメータ	自明でない動作、エッジケース	型シグネチャの再述
コンテキスト	標準的なキャンセル動作と異なる	標準的な ctx.Err() 返却
並行処理	あいまいなスレッド安全性（例：読み取りで変更）	読み取り専用は安全、変更は安全でない
クリーンアップ	リソース解放を常にドキュメント化	—
エラー	センチネル値、エラー型（*PathError を使用）	—
名前付き戻り値	同じ型の複数パラメータ、アクション指向の名前	型だけで十分に明確

重要な原則：

• コンテキストキャンセルが ctx.Err() を返すことは暗黙的です — 再述しないでください
• 読み取り専用の操作はスレッド安全と想定；変更は安全でないと想定 — 再述しないでください
• クリーンアップ要件を常にドキュメント化してください（例：Call Stop to release resources）
• エラー型ドキュメントではポインタを使用してください（*PathError）。正しい errors.Is/errors.As のため
• ネイキッドリターンを有効にするためだけに結果を名前付けしないでください — 明確さ > 簡潔さ

関数ドキュメントコメント内でパラメータ動作、コンテキストキャンセル、並行処理安全性、クリーンアップ要件、エラー返却、または名前付き戻り値パラメータをドキュメント化するときは references/CONVENTIONS.md を参照してください。

---

実行可能な例

勧告的: テストファイル（*_test.go）で実行可能な例を提供してください。

func ExampleConfig_WriteTo() {
    cfg := &Config{Name: "example"}
    cfg.WriteTo(os.Stdout)
    // Output:
    // {"name": "example"}
}

例は Godoc でドキュメント化要素に添付して表示されます。

実行可能な Example 関数を書く場合、例の命名規約（Example vs ExampleType_Method）を選択する場合、またはパッケージレベルの doc.go ファイルを追加する場合は references/EXAMPLES.md を参照してください。

---

Godoc フォーマット

Godoc の見出し、リンク、リスト、またはコードブロックのフォーマット、非推奨通知のためのシグナルブースティング、またはローカルでのドキュメント出力プレビューをする場合は references/FORMATTING.md を参照してください。

---

クイックリファレンス

トピック	重要なルール
ドキュメントコメント	名前で始まり、完全な文を使用
行の長さ	約80文字、可読性を優先
パッケージコメント	パッケージあたり1つ、package 句の上
パラメータ	自明でない動作のみドキュメント化
コンテキスト	暗黙的な動作の例外をドキュメント化
並行処理	あいまいなスレッド安全性をドキュメント化
クリーンアップ	リソース解放を常にドキュメント化
エラー	センチネルと型をドキュメント化（ポインタに注意）
例	テストファイルで実行可能な例を使用
フォーマット	段落は空行、コードはインデント

---

関連スキル

• 命名規約: ドキュメントコメントが説明する識別子の名前を選択する場合は go-naming を参照してください
• テスト例: godoc に表示される実行可能な Example テスト関数を書く場合は go-testing を参照してください
• リント強制: revive または他のリントを使用してドキュメントコメントの存在を強制する場合は go-linting を参照してください
• スタイル原則: ドキュメンテーション冗長性と明確さ・簡潔さのバランスを取る場合は go-style-core を参照してください