indexion-documentation

indexion documentation — 文档分析

评估文档状态并检测偏差。本技能涵盖文档生命周期的评估方面：哪些存在、哪些缺失、哪些过时。如需构建 README，请参见 indexion-readme。

“哪些需要文档？”

# 快速覆盖率概览 — 公共 API 有多少被文档化了？
indexion plan documentation --style=coverage .

报告：

• 总体覆盖率百分比（已文档化 / 总公共项）
• 按包细分，包含 README 存在情况
• 函数与类型的覆盖率拆分

输出示例：

总体覆盖率：81%（2285/2806）
函数：89%，类型：75%

如需包含优先级的详细计划：

# 完整计划，包含优先级和包清单
indexion plan documentation .

# 作为 GitHub Issue 进行跟踪
indexion plan documentation --format=github-issue .

# JSON 格式，便于脚本处理
indexion plan documentation --format=json .

如需快速列出每个文件中未文档化的项：

# 哪些 pub 声明缺少文档注释？
indexion grep --undocumented src/

检测原理： 使用 KGF 分词查找可见性关键字（pub、public、export）与声明关键字（fn、struct、enum、type、trait）的组合。将 /// 文档注释与声明关联。语言无关 — 适用于任何 KGF 支持的语言。

注意： 仅包含 ///| 标记的注释即使没有描述性文本也计为“已文档化”。请检查输出中的 doc_preview 以评估质量，而不仅仅是覆盖率。

“我的文档是最新的吗？”

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

# 完整的协调报告，markdown 格式
indexion plan reconcile --format=md .

此命令将代码符号与文档进行比较，并报告：

• 词汇差异：源代码中的术语在相关文档中缺失
• 过时文档：文档最后更新后代码已更改
• 缺失文档：没有文档覆盖的代码模块

阅读报告：

词汇差异表显示代码词汇与文档之间的距离（0-100%）。90% 以上的距离意味着 README 与当前代码基本无关。请检查“差距术语”列以查找具体缺失的词汇。

限定范围的检查：

# 仅检查包级文档
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 依赖关系" --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 的检测不会。

协调仅检查实现 -> 文档方向。 它检测代码中缺失的术语，但不会检测文档中引用了不存在的 CLI 选项。对于那个方向，请手动将每个 README 与 indexion <command> --help 进行比较。