indexion-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

indexion documentation — Documentation Analysis

indexion 文档——文档分析

Assess documentation state and detect drift. This skill covers the evaluation side of the documentation lifecycle: what exists, what's missing, what's stale. For building READMEs, see

indexion-readme

评估文档状态并检测漂移。该技能覆盖文档生命周期的评估环节：已有的内容、缺失的内容、过时的内容。如需生成README，请查看

indexion-readme

。

"What needs documentation?"

“哪些内容需要文档？”

bash

undefined

bash

undefined

Quick coverage overview — how much of the public API is documented?

快速概览覆盖率——公开API中有多少已文档化？

indexion plan documentation --style=coverage .


Reports:
- Overall coverage percentage (documented / total pub items)
- Per-package breakdown with README presence
- Functions vs types coverage split

Output example:

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


For a detailed plan with prioritized action items:

```bash

indexion plan documentation --style=coverage .


报告内容：
- 整体覆盖率百分比（已文档化项 / 全部公开项）
- 按包划分的README存在情况
- 函数与类型的覆盖率拆分

输出示例：

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


如需包含优先级操作项的详细规划：

```bash

Full plan with priorities and package inventory

包含优先级和包清单的完整规划

indexion plan documentation .

As a GitHub Issue for tracking

生成GitHub Issue用于跟踪

indexion plan documentation --format=github-issue .

JSON for scripting

生成JSON格式用于脚本处理

indexion plan documentation --format=json .


For a quick per-file listing of undocumented items:

```bash

indexion plan documentation --format=json .


如需快速查看每个文件中未文档化的项：

```bash

Which pub declarations lack doc comments?

哪些公开声明缺少文档注释？

indexion grep --undocumented src/


**How detection works:** Uses KGF tokenization to find visibility keywords
(`pub`, `public`, `export`) paired with declaration keywords (`fn`, `struct`,
`enum`, `type`, `trait`). Associates `///` doc comments with declarations.
Language-agnostic — works for any KGF-supported language.

**Caveat:** `///|` marker-only comments count as "documented" even without
descriptive text. Check `doc_preview` in the output for quality, not just coverage.

indexion grep --undocumented src/


**检测原理**：使用KGF分词技术查找可见性关键字（`pub`、`public`、`export`）与声明关键字（`fn`、`struct`、`enum`、`type`、`trait`）的组合，将`///`文档注释与声明关联。该方法与语言无关，适用于所有KGF支持的语言。

**注意**：仅含`///|`标记的注释即使没有描述性文本也会被算作“已文档化”。请查看输出中的`doc_preview`字段评估文档质量，而不只是覆盖率。

"Are my docs up to date?"

“我的文档是否最新？”

Detect drift between implementation code and documentation.

bash

undefined

检测实现代码与文档之间的漂移。

bash

undefined

Full reconcile report in markdown

生成Markdown格式的完整调和报告

indexion plan reconcile --format=md .


This compares code symbols against documentation and reports:
- **Vocabulary divergence**: source code terms missing from co-located docs
- **Stale docs**: code changed after docs were last updated
- **Missing docs**: code modules with no documentation coverage

**Read the report:**

The Vocabulary Divergence table shows distance (0-100%) between code vocabulary
and documentation. 90%+ distance means the README is essentially unrelated to
the current code. Check the Gap Terms column for specific missing vocabulary.

**Scoped checks:**

```bash

indexion plan reconcile --format=md .


该命令会对比代码符号与文档，并报告：
- **词汇差异**：源代码术语未出现在关联文档中
- **过时文档**：代码更新后文档未同步更新
- **缺失文档**：无文档覆盖的代码模块

**报告解读**：

词汇差异表展示了代码词汇与文档词汇之间的相似度（0-100%）。相似度90%以上意味着README与当前代码基本无关。查看“Gap Terms”列了解具体缺失的词汇。

**范围化检查**：

```bash

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 .


**Timestamp strategies:**

```bash

indexion plan reconcile --doc='docs/**/*.md' . indexion plan reconcile --doc-spec=markdown .


**时间戳策略**：

```bash

Use git commit timestamps (more accurate for collaborative projects)

使用Git提交时间戳（协作项目中更准确）

indexion plan reconcile --git .

Use file mtimes only (faster, no git dependency)

仅使用文件修改时间（速度更快，无需依赖Git）

indexion plan reconcile --mtime-only .


**Cache and drift:**

`plan reconcile` maintains a cache at `.indexion/cache/reconcile/`. After schema
changes or indexion upgrades, the cache can become stale and cause deserialization
errors. Clear it:

```bash
rm -rf .indexion/cache/reconcile

indexion plan reconcile --mtime-only .


**缓存与漂移**：

`plan reconcile`会在`.indexion/cache/reconcile/`目录维护缓存。在Schema变更或indexion版本升级后，缓存可能过时并导致反序列化错误。请清除缓存：

```bash
rm -rf .indexion/cache/reconcile

"Show me the dependency structure"

“展示依赖结构”

Generate dependency diagrams for understanding module relationships.

bash

undefined

生成依赖关系图以理解模块间的关联。

bash

undefined

Mermaid diagram (default — embeddable in GitHub README)

Mermaid图（默认格式——可嵌入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

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/ #机器可读格式

Custom title and output file

自定义标题和输出文件

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

undefined

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

undefined

Analysis Workflow

分析流程

bash

undefined

bash

undefined

1. What's the current state?

1. 当前状态如何？

indexion plan documentation --style=coverage .

2. What specific items lack docs?

2. 哪些具体项缺少文档？

indexion grep --undocumented src/

3. Has code drifted from existing docs?

3. 现有文档是否与代码存在漂移？

indexion plan reconcile --format=md .

4. What does the dependency structure look like?

4. 依赖结构是什么样的？

indexion doc graph --output=deps.mmd src/

5. Fix flagged docs, re-verify

5. 修复标记的文档问题，重新验证

indexion plan reconcile --format=md .

undefined

indexion plan reconcile --format=md .

undefined

Common Pitfalls

常见问题

"plan reconcile shows 90%+ divergence everywhere"

Auto-generated skeleton READMEs (API listing only) have high divergence because they lack the vocabulary of the actual implementation. Enrich them with descriptions of what the code does, not just what it exports.

"plan documentation says 100% coverage but docs are wrong"

Coverage measures presence of doc comments, not accuracy. A
```
///|
```
marker counts as documented. Use
```
plan reconcile
```
to check content accuracy.

"plan reconcile crashes on startup"

Cache deserialization error after schema changes. Clear it:
```
rm -rf .indexion/cache/reconcile
```

"plan reconcile detects drift I already fixed"

The
```
--git
```
flag uses commit timestamps. If you fixed docs but haven't committed, mtime-based detection (
```
--mtime-only
```
) will see the fix, but git-based won't.

Reconcile only checks implementation -> docs direction. It detects code terms missing from docs, but does NOT detect docs referencing nonexistent CLI options. For that direction, compare each README against

indexion <command> --help

manually.

“plan reconcile显示所有内容的相似度都在90%以上”

自动生成的骨架README（仅API列表）相似度很高，因为它们缺少实际实现的相关词汇。请补充代码功能描述，而不只是导出内容。

“plan documentation显示覆盖率100%但文档内容错误”

覆盖率仅衡量文档注释的存在与否，不评估准确性。仅含
```
///|
```
标记的注释也会被算作已文档化。请使用
```
plan reconcile
```
检查内容准确性。

“plan reconcile启动时崩溃”

Schema变更后出现缓存反序列化错误。请清除缓存：
```
rm -rf .indexion/cache/reconcile
```

“plan reconcile检测到我已修复的漂移”

```
--git
```
标记使用提交时间戳。如果您已修复文档但未提交，基于修改时间的检测（
```
--mtime-only
```
）会识别到修复，但基于Git的检测不会。

调和仅检查实现→文档的方向。它会检测文档中缺失的代码术语，但不会检测文档引用了不存在的CLI选项的情况。如需检查该方向，请手动将每个README与

indexion <command> --help

输出进行对比。