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 分词，查找与声明关键词（fn、struct、enum、type、trait）配对的可见性关键词（pub、public、export）。将 /// 文档注释与声明关联起来。与语言无关，适用于任何 KGF 支持的语言。

注意事项： 即使没有描述性文本，仅包含 ///| 标记的注释也会被视为“已编写文档”。请检查输出中的 doc_preview 来评估质量，而不只是关注覆盖率。

##“我的文档是否是最新的？”

检测实现代码与文档之间的偏差。

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

此操作会将代码符号与文档进行比对，并报告：

• 词汇差异：源码中的术语未出现在相邻文档中
• 过时文档：代码的修改时间晚于文档的最近更新时间
• 缺失文档：没有文档覆盖的代码模块

阅读报告：

“词汇差异”表会显示代码词汇与文档之间的差异度（0–100%）。差异度达到 90% 以上，表示 README 与当前代码基本无关。请查看“差异词汇”列，了解具体缺失的词汇。

指定范围的检查：

# 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 进行对照。