indexion-documentation

indexion documentation — 文件分析

評估文件狀態並偵測偏差。此技能涵蓋文件生命週期的評估面：哪些存在、哪些缺失、哪些過時。若要建立 README，請參閱 indexion-readme。

「哪些需要文件？」

# 快速覆蓋率概覽 — 公開 API 有多少已文件化？
indexion plan documentation --style=coverage .

報告內容：

• 整體覆蓋率百分比（已文件化 / 總公開項目）
• 各套件細項，包含 README 是否存在
• 函式與型別的覆蓋率拆分

輸出範例：

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

如需包含優先順序行動項目的詳細計畫：

# 完整計畫，含優先順序與套件清單
indexion plan documentation .

# 以 GitHub Issue 格式輸出，便於追蹤
indexion plan documentation --format=github-issue .

# JSON 格式，便於腳本處理
indexion plan documentation --format=json .

如需快速列出未文件化的檔案：

# 哪些公開宣告缺少文件註解？
indexion grep --undocumented src/

偵測原理： 使用 KGF 斷詞找出可見性關鍵字（pub、public、export）搭配宣告關鍵字（fn、struct、enum、type、trait）。將 /// 文件註解與宣告關聯。語言無關 — 適用於任何 KGF 支援的語言。

注意： 僅有 ///| 標記的註解即使沒有描述文字，仍算作「已文件化」。請檢查輸出中的 doc_preview 以評估品質，而不只是覆蓋率。

「我的文件是最新的嗎？」

偵測實作程式碼與文件之間的偏差。

# 以 Markdown 格式輸出完整的 reconcile 報告
indexion plan reconcile --format=md .

此命令比較程式碼符號與文件，並報告：

• 詞彙分歧：原始碼中出現但同位置文件中缺少的詞彙
• 過時文件：文件最後更新後程式碼已變更
• 缺少文件：沒有任何文件覆蓋的程式碼模組

閱讀報告：

詞彙分歧表格顯示程式碼詞彙與文件之間的距離（0-100%）。距離 90% 以上表示 README 與當前程式碼基本上無關。請檢查「Gap Terms」欄位以了解具體缺少的詞彙。

限定範圍檢查：

# 僅檢查套件層級文件
indexion plan reconcile --scope=package-docs .

# 僅檢查樹狀層級文件
indexion plan reconcile --scope=tree-docs .

# 檢查特定文件
indexion plan reconcile --doc='docs/**/*.md' .
indexion plan reconcile --doc-spec=markdown .

時間戳策略：

# 使用 git 提交時間戳（協作專案更準確）
indexion plan reconcile --git .

# 僅使用檔案修改時間（更快，無需 git 依賴）
indexion plan reconcile --mtime-only .

快取與偏差：

plan reconcile 在 .indexion/cache/reconcile/ 維護快取。結構變更或 indexion 升級後，快取可能過時並導致反序列化錯誤。清除方式：

rm -rf .indexion/cache/reconcile

「顯示相依性結構」

產生相依性圖表以了解模組關係。

# Mermaid 圖表（預設 — 可嵌入 GitHub README）
indexion doc graph src/config/

# 其他格式
indexion doc graph --format=dot src/     # Graphviz DOT
indexion doc graph --format=d2 src/      # D2
indexion doc graph --format=text src/    # ASCII 文字
indexion doc graph --format=json src/    # 機器可讀

# 自訂標題與輸出檔案
indexion doc graph --title="KGF Dependencies" --output=deps.mmd src/kgf/

分析工作流程

# 1. 當前狀態為何？
indexion plan documentation --style=coverage .

# 2. 哪些特定項目缺少文件？
indexion grep --undocumented src/

# 3. 程式碼是否偏離現有文件？
indexion plan reconcile --format=md .

# 4. 相依性結構長怎樣？
indexion doc graph --output=deps.mmd src/

# 5. 修正標記的文件，重新驗證
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 進行比較。