indexion-documentation

indexion のドキュメント — ドキュメント分析

ドキュメントの状態を評価し、乖離を検出します。このスキルは、ドキュメントのライフサイクルにおける評価の側面、つまり存在するもの、不足しているもの、古くなっているものを扱います。README の作成については、indexion-readme をご覧ください。

「何をドキュメント化する必要がありますか？」

# Quick coverage overview — how much of the public API is documented?
indexion plan documentation --style=coverage .

レポートの内容：

• 全体のカバレッジ率（ドキュメント化済み／公開アイテムの合計）
• README の有無を含む、パッケージごとの内訳
• 関数と型のカバレッジの内訳

出力例：

Overall Coverage: 81% (2285/2806)
Functions: 89%, Types: 75%

優先順位付きのアクションアイテムを含む詳細な計画を確認するには：

# Full plan with priorities and package inventory
indexion plan documentation .

# As a GitHub Issue for tracking
indexion plan documentation --format=github-issue .

# JSON for scripting
indexion plan documentation --format=json .

ドキュメント化されていないアイテムをファイルごとにすばやく一覧表示するには：

# Which pub declarations lack doc comments?
indexion grep --undocumented src/

検出の仕組み： KGF トークン化を使用して、可視性を示すキーワード （pub、public、export）と宣言キーワード（fn、struct、 enum、type、trait）の組み合わせを検出します。宣言に /// ドキュメントコメントを関連付けます。 言語に依存せず、KGF がサポートするあらゆる言語で動作します。

注意点： ///| のマーカーのみのコメントは、説明文がなくても「ドキュメント化済み」としてカウントされます。カバレッジだけでなく、出力の doc_preview で品質を確認してください。

「ドキュメントは最新ですか？」

実装コードとドキュメントの間の乖離を検出します。

# Full reconcile report in markdown
indexion plan reconcile --format=md .

コードのシンボルとドキュメントを比較し、次の項目を報告します：

• 語彙の乖離：ソースコード内の用語が、同じ場所にあるドキュメントに含まれていない
• 古いドキュメント：ドキュメントの最終更新後にコードが変更されている
• ドキュメントの不足：ドキュメントでカバーされていないコードモジュール

レポートの見方：

「Vocabulary Divergence」テーブルには、コードの語彙とドキュメントの間の乖離度（0～100％）が表示されます。乖離度が90％以上の場合、README は現在のコードと実質的に無関係です。具体的に不足している語彙については、「Gap Terms」列を確認してください。

対象を絞ったチェック：

# Check only package-level docs
indexion plan reconcile --scope=package-docs .

# Check only tree-level docs
indexion plan reconcile --scope=tree-docs .

# Check specific documents
indexion plan reconcile --doc='docs/**/*.md' .
indexion plan reconcile --doc-spec=markdown .

タイムスタンプの判定方法：

# Use git commit timestamps (more accurate for collaborative projects)
indexion plan reconcile --git .

# Use file mtimes only (faster, no git dependency)
indexion plan reconcile --mtime-only .

キャッシュと乖離：

plan reconcile は .indexion/cache/reconcile/ にキャッシュを保持します。スキーマの変更後や indexion のアップグレード後は、キャッシュが古くなり、デシリアライズエラーが発生することがあります。キャッシュを削除してください：

rm -rf .indexion/cache/reconcile

「依存関係の構造を確認する」

モジュール間の関係を把握するために、依存関係図を生成します。

# Mermaid diagram (default — embeddable in GitHub README)
indexion doc graph src/config/

# Other formats
indexion doc graph --format=dot src/     # Graphviz DOT
indexion doc graph --format=d2 src/      # D2
indexion doc graph --format=text src/    # ASCII text
indexion doc graph --format=json src/    # Machine-readable

# Custom title and output file
indexion doc graph --title="KGF Dependencies" --output=deps.mmd src/kgf/

分析のワークフロー

# 1. What's the current state?
indexion plan documentation --style=coverage .

# 2. What specific items lack docs?
indexion grep --undocumented src/

# 3. Has code drifted from existing docs?
indexion plan reconcile --format=md .

# 4. What does the dependency structure look like?
indexion doc graph --output=deps.mmd src/

# 5. Fix flagged docs, re-verify
indexion plan reconcile --format=md .

よくある落とし穴

「plan reconcile でどこを見ても乖離度が90％以上になる」

• 自動生成された骨組みの README（API の一覧のみ）は、実際の実装で使われている語彙を含まないため、乖離度が高くなります。エクスポートされるものだけでなく、コードが何をするのかを説明する内容を加えてください。

「plan documentation ではカバレッジが100％なのに、ドキュメントが間違っている」

• カバレッジが測定するのはドキュメントコメントの有無であり、正確性ではありません。///| マーカーもドキュメント化済みとしてカウントされます。内容の正確性を確認するには、plan reconcile を使用してください。

「plan reconcile の起動時にクラッシュする」

• スキーマの変更後に発生するキャッシュのデシリアライズエラーです。キャッシュを削除してください： rm -rf .indexion/cache/reconcile

「修正済みの乖離が plan reconcile で検出される」

• --git フラグはコミットのタイムスタンプを使用します。ドキュメントを修正してもまだコミットしていない場合、更新日時ベースの検出（--mtime-only）では修正が認識されますが、Git ベースの検出では認識されません。

Reconcile がチェックするのは、実装からドキュメントへの方向のみです。ドキュメントに含まれていないコードの用語は検出しますが、存在しない CLI オプションをドキュメントが参照していることは検出しません。その方向を確認するには、各 README を indexion <command> --help と手動で照合してください。