手順
- ドキュメント対象の特定:
- ユーザー指定がある場合: その関数/パッケージ
- 指定がない場合: GoDocコメントが不足している公開関数を検出
- 既存ドキュメントの分析:
- 既存のコメントスタイルを確認
- README.md の構造を把握
- CHANGELOG.md のフォーマットを確認
- GoDocコメントの生成:
- 公開関数（大文字始まり）に対してコメント追加
- GoDocの規約に従う（関数名で始める）
- パラメータ、戻り値、エラーの説明
- 使用例の生成:
Example テスト関数を作成（go test で検証可能）- 典型的なユースケースを示す
- README更新:
- API仕様セクションを更新/追加
- インストール方法
- クイックスタート
- 使用例
- 検証:
go doc で生成結果を確認go test でExampleが動作することを確認
GoDocコメントのベストプラクティス
関数コメント
// Sum calculates the sum of all integers in the provided slice.
// It returns 0 for an empty or nil slice.
//
// Example:
// result := Sum([]int{1, 2, 3}) // returns 6
func Sum(nums []int) int { ... }
パッケージコメント
// Package calc provides basic mathematical calculation utilities.
//
// This package includes functions for arithmetic operations
// such as sum, average, and statistical calculations.
package calc
型コメント
// Calculator performs arithmetic operations with state management.
type Calculator struct {
// Total holds the running sum
Total int
}
Example テストの生成
func ExampleSum() {
result := Sum([]int{1, 2, 3, 4, 5})
fmt.Println(result)
// Output: 15
}
func ExampleSum_empty() {
result := Sum([]int{})
fmt.Println(result)
// Output: 0
}
README.md テンプレート
# Package Name
Brief description of what this package does.
## Installation
\`\`\`bash
go get github.com/user/repo/pkg/calc
\`\`\`
## Usage
\`\`\`go
package main
import "github.com/user/repo/pkg/calc"
func main() {
result := calc.Sum([]int{1, 2, 3})
fmt.Println(result) // 6
}
\`\`\`
## API Reference
### func Sum(nums []int) int
Calculates the sum of all integers in the slice.
**Parameters:**
- `nums`: Slice of integers to sum
**Returns:**
- Sum of all elements (0 for empty/nil slice)
## License
MIT
CHANGELOG.md 更新
# Changelog
## [Unreleased]
### Added
- GoDoc comments for all public functions
- Example tests for Sum function
- API reference in README
### Changed
- Improved documentation clarity
ドキュメント品質チェック
ベストプラクティス
- 簡潔に（1-3文）
- 専門用語は避けるか、説明を添える
- コードを読まなくても使い方が分かるレベルで
- 「何をするか」だけでなく「いつ使うべきか」も含める
- Exampleは実際に動作するコードに
majiayu000