Initial commit
This commit is contained in:
Zhongwei Li
306
commands/update-doc-string.md
Normal file
306
commands/update-doc-string.md
Normal file
@@ -0,0 +1,306 @@
|
||||
## Update Doc String
|
||||
|
||||
多言語対応の docstring/コメントを体系的に管理し、高品質なドキュメントを維持します。
|
||||
|
||||
### 使い方
|
||||
|
||||
```bash
|
||||
# 言語を自動検出して実行
|
||||
「docstring がないクラス・関数に追加し、基準を満たさないコメントを更新してください」
|
||||
|
||||
# 言語を指定して実行
|
||||
/update-doc-string --lang python
|
||||
「Python ファイルの docstring を PEP 257 準拠で更新してください」
|
||||
|
||||
# 特定ディレクトリのドキュメント整備
|
||||
「src/components/ 配下の関数に JSDoc を追加してください」
|
||||
```
|
||||
|
||||
### オプション
|
||||
|
||||
- `--lang <en|ja>` : ドキュメントの記述言語 (デフォルト: 既存コメントから自動判定、なければ en)
|
||||
- `--style <スタイル>` : ドキュメントスタイルを指定 (言語固有のデフォルトあり)
|
||||
- `--marker <true|false>` : Claude マーカーを付与するか (デフォルト: true)
|
||||
|
||||
### 基本例
|
||||
|
||||
```bash
|
||||
# 1. 対象ファイルの分析 (プログラミング言語は自動検出)
|
||||
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
|
||||
「docstring が不足している要素 (コメント行数 0 または 30 文字未満) を特定してください」
|
||||
|
||||
# 2. ドキュメント追加 (言語自動判定)
|
||||
「特定された要素に言語固有の必須要素を含む docstring を追加してください」
|
||||
# → 既存コメントに日本語があれば日本語で、なければ英語で記述
|
||||
|
||||
# 3. ドキュメント追加 (明示的に英語指定)
|
||||
/update-doc-string --lang en
|
||||
「Add docstrings with required elements to the identified elements」
|
||||
|
||||
# 4. マーカー確認
|
||||
「追加・更新したすべての docstring に Claude マーカーがあることを確認してください」
|
||||
```
|
||||
|
||||
### 実行手順
|
||||
|
||||
#### 1. 対象要素の優先順位
|
||||
|
||||
1. 🔴 **最優先**: docstring/コメントがない要素 (コメント行数 0)
|
||||
2. 🟡 **次優先**: 基準を満たさない要素 (30 文字未満または必須要素欠如)
|
||||
3. 🟢 **確認対象**: Claude マーカーがない既存コメント
|
||||
|
||||
**対象要素 (言語共通)**:
|
||||
|
||||
- Class/クラス定義
|
||||
- Function/関数・メソッド
|
||||
- Module/モジュール (Python, Go)
|
||||
- Enum/列挙型
|
||||
- Interface/インターフェース (TypeScript, Go)
|
||||
|
||||
#### 2. 言語別記述ルール
|
||||
|
||||
**Python (PEP 257)**:
|
||||
|
||||
```python
|
||||
# 日本語版 (デフォルト)
|
||||
def calculate_total(items: List[Item]) -> float:
|
||||
"""アイテムリストの合計金額を計算します。(30-60 文字)
|
||||
|
||||
各アイテムの価格と数量を掛け合わせ、税込み合計を返します。
|
||||
空のリストの場合は 0.0 を返します。(50-200 文字)
|
||||
|
||||
Args:
|
||||
items: 計算対象のアイテムリスト
|
||||
|
||||
Returns:
|
||||
税込み合計金額
|
||||
|
||||
Generated by Claude 🤖
|
||||
"""
|
||||
|
||||
# 英語版 (--lang en)
|
||||
def calculate_total(items: List[Item]) -> float:
|
||||
"""Calculate the total amount for a list of items. (30-60 chars)
|
||||
|
||||
Multiplies the price and quantity of each item and returns
|
||||
the total with tax. Returns 0.0 for empty lists. (50-200 chars)
|
||||
|
||||
Args:
|
||||
items: List of items to calculate
|
||||
|
||||
Returns:
|
||||
Total amount with tax
|
||||
|
||||
Generated by Claude 🤖
|
||||
"""
|
||||
```
|
||||
|
||||
**JavaScript/TypeScript (JSDoc)**:
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* ユーザープロフィールを表示するコンポーネントです。(30-60 文字)
|
||||
*
|
||||
* アバター画像、ユーザー名、ステータス情報を表示し、
|
||||
* クリック時にプロフィール詳細画面へ遷移します。(50-200 文字)
|
||||
*
|
||||
* @param {Object} props - コンポーネントのプロパティ
|
||||
* @param {string} props.userId - ユーザー ID
|
||||
* @param {boolean} [props.showStatus=true] - ステータス表示フラグ
|
||||
* @returns {JSX.Element} レンダリングされたコンポーネント
|
||||
*
|
||||
* @generated by Claude 🤖
|
||||
*/
|
||||
const UserProfile = ({ userId, showStatus = true }) => {
|
||||
```
|
||||
|
||||
**Go**:
|
||||
|
||||
```go
|
||||
// CalculateTotal はアイテムリストの合計金額を計算します。(30-60 文字)
|
||||
//
|
||||
// 各アイテムの価格と数量を掛け合わせ、税込み合計を返します。
|
||||
// 空のスライスの場合は 0.0 を返します。(50-200 文字)
|
||||
//
|
||||
// Generated by Claude 🤖
|
||||
func CalculateTotal(items []Item) float64 {
|
||||
```
|
||||
|
||||
**Rust**:
|
||||
|
||||
```rust
|
||||
/// アイテムリストの合計金額を計算します。(30-60 文字)
|
||||
///
|
||||
/// 各アイテムの価格と数量を掛け合わせ、税込み合計を返します。
|
||||
/// 空のベクタの場合は 0.0 を返します。(50-200 文字)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
pub fn calculate_total(items: &[Item]) -> f64 {
|
||||
```
|
||||
|
||||
**Dart (DartDoc)**:
|
||||
|
||||
```dart
|
||||
/// ユーザープロフィールを表示する Widget です。(30-60 文字)
|
||||
///
|
||||
/// アバター画像、ユーザー名、ステータス情報を縦に配置し、
|
||||
/// タップ時にプロフィール詳細画面へ遷移します。(50-200 文字)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
class UserProfileWidget extends StatelessWidget {
|
||||
```
|
||||
|
||||
#### 3. 既存コンテンツ保持ルール
|
||||
|
||||
1. **既存コメントが基準を満たす場合**: そのまま保持 (新規追加しない)
|
||||
- 基準: 30 文字以上かつ必須要素 (概要・詳細・マーカー) を含む
|
||||
2. **既存コメントが基準を満たさない場合**: 完全に置き換え (重複させない)
|
||||
3. **既存コメントがない場合**: 新しいコメントを追加
|
||||
|
||||
**保持すべき重要情報**:
|
||||
|
||||
- URL やリンク: `See also:`, `@see`, `参照:` など
|
||||
- TODO コメント: `TODO:`, `FIXME:`, `XXX:` 形式
|
||||
- 注意事項: `Note:`, `Warning:`, `注意:` など
|
||||
- 使用例: `Example:`, `例:`, `# Examples` など
|
||||
- 既存のパラメータ・戻り値説明
|
||||
|
||||
### 言語別設定
|
||||
|
||||
```yaml
|
||||
# 言語別デフォルト設定
|
||||
languages:
|
||||
python:
|
||||
style: "google" # google, numpy, sphinx
|
||||
indent: 4
|
||||
quotes: '"""'
|
||||
|
||||
javascript:
|
||||
style: "jsdoc"
|
||||
indent: 2
|
||||
prefix: "/**"
|
||||
suffix: "*/"
|
||||
|
||||
typescript:
|
||||
style: "tsdoc"
|
||||
indent: 2
|
||||
prefix: "/**"
|
||||
suffix: "*/"
|
||||
|
||||
go:
|
||||
style: "godoc"
|
||||
indent: 0
|
||||
prefix: "//"
|
||||
|
||||
rust:
|
||||
style: "rustdoc"
|
||||
indent: 0
|
||||
prefix: "///"
|
||||
|
||||
dart:
|
||||
style: "dartdoc"
|
||||
indent: 0
|
||||
prefix: "///"
|
||||
```
|
||||
|
||||
### 品質チェックリスト
|
||||
|
||||
- ✅ **文字数**: 概要 30-60 文字、詳細 50-200 文字を厳守
|
||||
- ✅ **必須要素**: 概要・詳細説明・Claude マーカーの 3 要素を必ず含む
|
||||
- ✅ **完全性**: 役割・使用コンテキスト・注意点を記載
|
||||
- ✅ **言語規約**: 各言語の公式スタイルガイドに準拠
|
||||
- ✅ **例外**: エラー・例外の説明 (該当する場合)
|
||||
- ✅ **正確性**: 実装を分析し、事実に基づいた記述のみ
|
||||
|
||||
### 注意事項
|
||||
|
||||
**🔴 絶対禁止事項**:
|
||||
|
||||
- ❌ ドキュメントコメント以外のコード変更
|
||||
- ❌ 実装詳細に関する推測 (事実のみ記載)
|
||||
- ❌ 言語規約に反するフォーマット
|
||||
- ❌ 既存の型アノテーションの削除・変更
|
||||
- ❌ 既存コメントとの重複
|
||||
- ❌ テストファイルへの文字数基準未満のコメント
|
||||
|
||||
**実行と検証**:
|
||||
|
||||
```bash
|
||||
# 実行結果の記録
|
||||
ADDED_COMMENTS=0
|
||||
UPDATED_COMMENTS=0
|
||||
ERRORS=0
|
||||
|
||||
# 既存コメントから言語を自動判定
|
||||
# 日本語文字 (ひらがな・カタカナ・漢字) を検出したら ja、それ以外は en
|
||||
DOC_LANGUAGE="en" # デフォルト
|
||||
if grep -r '[ぁ-んァ-ヶー一-龠]' --include="*.py" --include="*.js" --include="*.ts" --include="*.dart" --include="*.go" --include="*.rs" . 2>/dev/null | head -n 1; then
|
||||
DOC_LANGUAGE="ja"
|
||||
fi
|
||||
|
||||
# プログラミング言語の自動検出と静的解析
|
||||
if [ -f "*.py" ]; then
|
||||
pylint --disable=all --enable=missing-docstring .
|
||||
elif [ -f "*.js" ] || [ -f "*.ts" ]; then
|
||||
eslint . --rule 'jsdoc/require-jsdoc: error'
|
||||
elif [ -f "*.go" ]; then
|
||||
golint ./...
|
||||
elif [ -f "*.rs" ]; then
|
||||
cargo doc --no-deps
|
||||
elif [ -f "*.dart" ]; then
|
||||
melos analyze
|
||||
fi
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "🔴 エラー: 静的解析が失敗しました"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 実行サマリーの出力
|
||||
echo "📊 実行結果:"
|
||||
echo "- ドキュメント言語: $DOC_LANGUAGE"
|
||||
echo "- 追加したコメント: $ADDED_COMMENTS 件"
|
||||
echo "- 更新したコメント: $UPDATED_COMMENTS 件"
|
||||
echo "- エラー発生数: $ERRORS 件"
|
||||
```
|
||||
|
||||
### 実行成功基準
|
||||
|
||||
1. **完了判定**: 以下をすべて満たす場合に成功
|
||||
- 言語固有の静的解析が PASSED
|
||||
- エラー発生数が 0
|
||||
- 追加・更新したコメントがすべて基準を満たす
|
||||
|
||||
2. **部分成功**: 以下の場合
|
||||
- エラー発生数が 5 件未満
|
||||
- 全体の 90% 以上が基準を満たす
|
||||
|
||||
3. **失敗**: 以下の場合
|
||||
- 静的解析が FAILED
|
||||
- エラー発生数が 5 件以上
|
||||
|
||||
### Claude との連携
|
||||
|
||||
```bash
|
||||
# プロジェクト全体の分析 (言語自動判定)
|
||||
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
|
||||
/update-doc-string
|
||||
「このプロジェクトの docstring を言語別のベストプラクティスに従って更新して」
|
||||
# → 既存コメントに日本語があれば ja、なければ en で実行
|
||||
|
||||
# 明示的に英語ドキュメントで実行
|
||||
/update-doc-string --lang en
|
||||
"Update docstrings following language-specific best practices"
|
||||
|
||||
# 明示的に日本語ドキュメントで実行
|
||||
/update-doc-string --lang ja
|
||||
「このプロジェクトの docstring を言語別のベストプラクティスに従って更新して」
|
||||
|
||||
# マーカーなしで実行 (言語自動判定)
|
||||
/update-doc-string --marker false
|
||||
"Improve existing docstrings without adding Claude markers"
|
||||
|
||||
# 英語ドキュメント、マーカーなし
|
||||
/update-doc-string --lang en --marker false
|
||||
"Improve existing docstrings without adding Claude markers"
|
||||
```
|
||||
Reference in New Issue
Block a user