go-documentation

Go ドキュメント

リソースのルーティング

• scripts/check-docs.sh - エクスポートされた関数、型、メソッド、定数、パッケージにドキュメントコメントが不足していないか確認するときに実行します。
• scripts/check-docs-ast.go - check-docs.sh から呼び出される実装ヘルパーです。ドキュメント分析の動作を変更する場合は、こちらを修正してください。
• assets/doc-template.go - ドキュメント付きのパッケージやエクスポートされた API を作成するときに使用します。
• references/CONVENTIONS.md - パラメーター、コンテキストの動作、並行処理の安全性、クリーンアップ、エラー、名前付き戻り値をドキュメント化するときに参照してください。
• references/EXAMPLES.md - 実行可能な例やパッケージの例を追加するときに参照してください。
• references/FORMATTING.md - Godoc のリスト、段落、リンク、コードブロックを整形するときに参照してください。

---

ドキュメントコメント

規範：トップレベルのエクスポートされた名前には、すべてドキュメントコメントが必要です。

基本ルール

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) { ...

動作が自明でない非エクスポート型や関数にも、ドキュメントコメントを付けてください。

検証：ドキュメントコメントを追加したら、bash scripts/check-docs.sh を実行して、ドキュメントが不足しているエクスポートシンボルがないことを確認してください。続行する前に、不足箇所をすべて修正してください。

---

コメントの文

規範：ドキュメントコメントは完全な文でなければなりません。

• 先頭の単語を大文字にし、句読点で終えます
• 例外：明確であれば、大文字にしない識別子で始めてもかまいません
• 構造体フィールドの行末コメントは、句や語句でもかまいません

---

コメントの行の長さ

推奨：目安は約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 ファイルを使用します

---

ドキュメント化する内容

推奨：自明な動作ではなく、自明でない動作をドキュメント化します。

トピック	ドキュメント化する場合...	省略する場合...
パラメーター	自明でない動作、エッジケースがある	型シグネチャを言い換えるだけになる
コンテキスト	標準的なキャンセル処理と動作が異なる	標準的な ctx.Err() を返す
並行処理	スレッドセーフかどうかが曖昧（例：読み取りが状態を変更する）	読み取り専用は安全で、変更は安全でない
クリーンアップ	リソースの解放は必ず記載する	—
エラー	センチネル値、エラー型（*PathError を使用）	—
名前付き戻り値	同じ型のパラメーターが複数ある、動作を示す名前を付ける	型だけで十分に明確である

主な原則：

• コンテキストのキャンセル時に ctx.Err() を返すのは暗黙的です。言い直さないでください
• 読み取り専用操作はスレッドセーフ、変更操作はスレッドセーフでないと想定されます。言い直さないでください
• クリーンアップの要件は必ず記載してください（例：Call Stop to release resources）
• errors.Is／errors.As を正しく使えるよう、エラー型のドキュメントではポインターを使用してください（*PathError）
• 名前のない戻り値を使えるようにするだけの目的で戻り値に名前を付けないでください。簡潔さより明確さを優先します

---

実行可能な例

推奨：テストファイル（*_test.go）に実行可能な例を記述します。

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

例は、ドキュメント化する要素に関連付けられた Godoc に表示されます。

---

クイックリファレンス

トピック	主なルール
ドキュメントコメント	名前から始め、完全な文にする
行の長さ	約80文字を目安にし、読みやすさを優先する
パッケージコメント	パッケージごとに1つ、package 節の直前に置く
パラメーター	自明でない動作のみを記載する
コンテキスト	暗黙の動作に対する例外を記載する
並行処理	スレッドセーフかどうかが曖昧な場合に記載する
クリーンアップ	リソースの解放を必ず記載する
エラー	センチネルと型を記載する（ポインターに注意）
例	テストファイルに実行可能な例を記述する
書式	段落間は空行を入れ、コードはインデントする

---

関連するスキル

• 命名規則：ドキュメントコメントで説明する識別子の名前を選ぶ際は、go-namingを参照してください
• テストの例：godocに表示される、実行可能なExampleテスト関数を作成する際は、go-testingを参照してください
• リンティングによる強制：reviveなどのリンターを使用してドキュメントコメントの記述を強制する際は、go-lintingを参照してください
• スタイルの原則：ドキュメントの詳しさと明確さ・簡潔さのバランスを取る際は、go-style-coreを参照してください