mcpField
C
code-documentation

code-documentation

github.com/aj-geddes開発375496 回インストール35 週間前に更新
リポジトリ

code-documentation について

言語ごとの規約に沿ってコードドキュメントを書くスキルです。API、関数、クラス、型を記述する開発者向けで、例や正確な情報、保守しやすいコメントを重視します。

主な機能

  1. 01JSDoc、docstring、JavaDocのガイド
  2. 02関数とクラスのドキュメント
  3. 03APIと型のドキュメント
  4. 04例、引数、戻り値の説明

活用シーン

  1. 01公開関数やクラスの文書化
  2. 02コードからのAPIドキュメント作成
  3. 03使用例やエラー情報の追加

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill code-documentation

インストール後、Claude Code で/code-documentationを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
class-documentation-2.md
class-documentation.md
function-documentation-2.md
function-documentation.md
module-documentation.md
type-definitions.md
templates/
doc-template.md

詳細

コードドキュメント

目次

概要

JSDoc、Python の docstring、JavaDoc、インラインコメントなど、言語ごとの標準を使用して、明確で包括的なコードドキュメントを作成します。

使用するタイミング

  • 関数やクラスのドキュメント
  • JavaScript/TypeScript の JSDoc
  • Python の docstring
  • Java の JavaDoc
  • インラインコードコメント
  • コードからの API ドキュメント作成
  • 型定義
  • コード内の使用例

クイックスタート

最小限の実用例：

/**
 * Calculates the total price including tax and discount.
 *
 * @param {number} basePrice - The base price before tax and discount
 * @param {number} taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
 * @param {number} [discount=0] - Optional discount amount
 * @returns {number} The final price after tax and discount
 * @throws {Error} If basePrice or taxRate is negative
 *
 * @example
 * const price = calculateTotalPrice(100, 0.08, 10);
 * console.log(price); // 98
 *
 * @example
 * // Without discount
 * const price = calculateTotalPrice(100, 0.08);
 * console.log(price); // 108
 */
function calculateTotalPrice(basePrice, taxRate, discount = 0) {
  if (basePrice < 0 || taxRate < 0) {
    throw new Error("Price and tax rate must be non-negative");
  }
  return basePrice * (1 + taxRate) - discount;
}

// ... (see reference guides for full implementation)

リファレンスガイド

references/ ディレクトリにある詳細な実装：

ガイド内容
関数のドキュメント関数のドキュメント
クラスのドキュメントクラスのドキュメント
型定義型定義
関数のドキュメント関数のドキュメント
クラスのドキュメントクラスのドキュメント
モジュールのドキュメントモジュールのドキュメント

ベストプラクティス

✅ 推奨
  • 公開 API を十分にドキュメント化します
  • 使用例を含めます
  • パラメーターと戻り値をドキュメント化します
  • 発生する例外やエラーを明記します
  • 言語ごとの標準（JSDoc、docstring など）を使用します
  • コメントを最新の状態に保ちます
  • 「何を」ではなく「なぜ」をドキュメント化します
  • エッジケースや注意点を含めます
  • 関連する関数へのリンクを追加します
  • 型定義をドキュメント化します
  • 一貫した書式を使用します
❌ 非推奨
  • コメントで自明なことを説明する
  • コメントアウトしたコードを残す
  • 誤解を招くコメントを書く
  • 複雑な関数の使用例を省略する
  • 曖昧なパラメーターの説明を使う
  • コードの変更時にドキュメントを更新し忘れる
  • 単純なコードに過剰なコメントを付ける

コメント

Markdown 対応