Repository navigation
docs(design): rewrite and update design documents - #472
Conversation
Simplify project positioning, remove marketing language, update module descriptions to match current code, and fix cross-references to renamed design documents.
📝 WalkthroughWalkthroughDesign docs were renamed and expanded in English and Chinese, with sidebar and cross-link updates to match the new targets. Overview pages were condensed, and new or rewritten articles now cover command resolution, incremental parsing, module graphs, symbol indexing, dependency scanning, and template resolution. ChangesDesign Documentation Overhaul
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
16bit-ykiko
changed the title
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d0bb54b816
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (8)
docs/zh/design/dependency-scanning.md (2)
68-68: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd language specifier to fenced code block.
The fenced code block on this line lacks a language specifier. While the content is a text diagram, adding
textas the language tag satisfies the lint rule and improves consistency.- ``` + ```text [Quoted (-iquote)] [Angled (-I)] [System (-isystem)] [After (-idirafter)]<details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/zh/design/dependency-scanning.mdat line 68, The fenced diagram block
in the dependency-scanning docs is missing a language tag and should be updated
to use a text specifier. Locate the fenced block in the markdown and add the
text language identifier to the opening fence so it matches the lint rule while
preserving the diagram content.</details> <!-- cr-comment:v1:4978bce73a6f073ac276f017 --> _Source: Linters/SAST tools_ --- `94-94`: _📐 Maintainability & Code Quality_ | _🔵 Trivial_ | _💤 Low value_ **Add language specifier to fenced code block.** The fenced code block on this line lacks a language specifier. Add `text` to the opening fence since it contains an ASCII diagram. ```diff - ``` + ```text Wave 0: CDB 中的源文件 ──→ 扫描 ──→ 解析 include ──→ 发现头文件<details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/zh/design/dependency-scanning.mdat line 94, The fenced code block in
the dependency scanning design doc is missing a language specifier; update the
opening fence for the ASCII diagram to use text so it is properly labeled.
Locate the fenced block containing the “Wave 0” diagram and change the opening
delimiter to the text variant, keeping the rest of the diagram unchanged.</details> <!-- cr-comment:v1:c6056749925ce1593a491a3d --> _Source: Linters/SAST tools_ </blockquote></details> <details> <summary>docs/zh/design/symbol-index.md (1)</summary><blockquote> `61-61`: _📐 Maintainability & Code Quality_ | _🔵 Trivial_ | _💤 Low value_ **Add language identifier to index hierarchy diagram code block.** The fenced code block containing the three-level index hierarchy ASCII diagram should specify `text` as the language identifier to satisfy markdownlint MD040. ```diff -``` +```text TUIndex 一次编译的原始产物，合并后丢弃 ...🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/zh/design/symbol-index.md` at line 61, The fenced ASCII diagram in the index hierarchy section is missing a language identifier, which triggers markdownlint MD040. Update the code block that contains the three-level hierarchy diagram to use the text language tag so the markdown renderer recognizes it properly; this is the block near the index hierarchy content in symbol-index.md.Source: Linters/SAST tools
docs/en/design/symbol-index.md (1)
61-61: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd language identifier to index hierarchy diagram code block.
The fenced code block containing the three-level index hierarchy ASCII diagram should specify
textas the language identifier to satisfy markdownlint MD040.-``` +```text TUIndex Raw artifact from a single compilation, discarded after merging ...🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/en/design/symbol-index.md` at line 61, The fenced code block in the symbol index hierarchy diagram is missing a language identifier, which triggers markdownlint MD040. Update the code fence around the three-level index hierarchy ASCII diagram in the symbol-index document to use the text language identifier, and keep the rest of the diagram content unchanged.Source: Linters/SAST tools
docs/zh/design/module-graph.md (1)
1-171: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueContent review: Comprehensive and well-structured module compilation design document.
The document effectively explains the CompileGraph design with clear motivation from clangd's limitations. Key technical decisions (interest counting, lazy construction, generation counters, RAII guards) are well-justified. The FAQ section directly addresses likely reader questions. Known limitations are honestly disclosed with improvement directions.
One minor observation: The document mentions
kotatsu(line 131) without prior introduction - readers unfamiliar with the project's coroutine framework may need context. Consider adding a brief parenthetical on first use.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/zh/design/module-graph.md` around lines 1 - 171, The document first introduces kotatsu in the RAII/structured concurrency section without context, so add a brief parenthetical explanation on its first mention in the CompileGraph implementation overview. Update the paragraph that references kota::task_group and协程取消 to identify kotatsu as the project’s coroutine/runtime framework so readers can understand the terminology without prior knowledge. Keep the change localized to the affected section and preserve the existing explanation of RefGuard and UnitGuard.docs/zh/design/incremental-parse.md (1)
116-116: 🧹 Nitpick | 🔵 TrivialOptional: Add language specifier to ASCII art code block to silence markdownlint (ZH version).
Same as the EN version, adding
textto the fenced code block would silence the markdownlint warning without affecting rendering.+```text
<details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/zh/design/incremental-parse.mdat line 116, The ASCII art fenced block
in the ZH incremental parse design doc is missing a language specifier, which
triggers markdownlint. Update the affected fenced block to use the same approach
as the EN version by adding the text specifier to the code fence, keeping the
existing ASCII art and rendering unchanged.</details> <!-- cr-comment:v1:dc5d822859d4934dc4f6b894 --> _Source: Linters/SAST tools_ </blockquote></details> <details> <summary>docs/en/design/module-graph.md (1)</summary><blockquote> `82-82`: _🧹 Nitpick_ | _🔵 Trivial_ **Optional: Add language specifier to ASCII art code block to silence markdownlint.** The markdownlint warning MD040 suggests adding a language specifier to the fenced code block at Line 82. While this is ASCII art rather than code, adding `text` as the language specifier would silence the warning without affecting rendering. ```diff+```text
<details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/en/design/module-graph.mdat line 82, The fenced ASCII art block in the
module-graph markdown is triggering markdownlint MD040 because it lacks a
language specifier. Update the code fence around the ASCII art to use a neutral
specifier like text so the block still renders the same while satisfying
linting; look for the fenced block in the document’s diagram section and adjust
that fence only.</details> <!-- cr-comment:v1:026764d913f119658bba6003 --> _Source: Linters/SAST tools_ </blockquote></details> <details> <summary>docs/en/design/incremental-parse.md (1)</summary><blockquote> `116-116`: _🧹 Nitpick_ | _🔵 Trivial_ **Optional: Add language specifier to ASCII art code block to silence markdownlint.** The markdownlint warning MD040 suggests adding a language specifier to the fenced code block at Line 116. While this is ASCII art rather than code, adding `text` as the language specifier would silence the warning without affecting rendering. ```diff+```text
<details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/en/design/incremental-parse.mdat line 116, Add a language specifier to
the fenced ASCII art block so markdownlint MD040 is silenced; update the
markdown block in the incremental parse design doc to use a text-labeled fence,
keeping the diagram content unchanged. Locate the fenced block around the ASCII
art snippet and adjust it consistently wherever that block is defined.</details> <!-- cr-comment:v1:1d35bbab5764373d728b1c30 --> _Source: Linters/SAST tools_ </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Nitpick comments:
In@docs/en/design/incremental-parse.md:
- Line 116: Add a language specifier to the fenced ASCII art block so
markdownlint MD040 is silenced; update the markdown block in the incremental
parse design doc to use a text-labeled fence, keeping the diagram content
unchanged. Locate the fenced block around the ASCII art snippet and adjust it
consistently wherever that block is defined.In
@docs/en/design/module-graph.md:
- Line 82: The fenced ASCII art block in the module-graph markdown is triggering
markdownlint MD040 because it lacks a language specifier. Update the code fence
around the ASCII art to use a neutral specifier like text so the block still
renders the same while satisfying linting; look for the fenced block in the
document’s diagram section and adjust that fence only.In
@docs/en/design/symbol-index.md:
- Line 61: The fenced code block in the symbol index hierarchy diagram is
missing a language identifier, which triggers markdownlint MD040. Update the
code fence around the three-level index hierarchy ASCII diagram in the
symbol-index document to use the text language identifier, and keep the rest of
the diagram content unchanged.In
@docs/zh/design/dependency-scanning.md:
- Line 68: The fenced diagram block in the dependency-scanning docs is missing a
language tag and should be updated to use a text specifier. Locate the fenced
block in the markdown and add the text language identifier to the opening fence
so it matches the lint rule while preserving the diagram content.- Line 94: The fenced code block in the dependency scanning design doc is
missing a language specifier; update the opening fence for the ASCII diagram to
use text so it is properly labeled. Locate the fenced block containing the “Wave
0” diagram and change the opening delimiter to the text variant, keeping the
rest of the diagram unchanged.In
@docs/zh/design/incremental-parse.md:
- Line 116: The ASCII art fenced block in the ZH incremental parse design doc is
missing a language specifier, which triggers markdownlint. Update the affected
fenced block to use the same approach as the EN version by adding the text
specifier to the code fence, keeping the existing ASCII art and rendering
unchanged.In
@docs/zh/design/module-graph.md:
- Around line 1-171: The document first introduces kotatsu in the
RAII/structured concurrency section without context, so add a brief
parenthetical explanation on its first mention in the CompileGraph
implementation overview. Update the paragraph that references kota::task_group
and协程取消 to identify kotatsu as the project’s coroutine/runtime framework so
readers can understand the terminology without prior knowledge. Keep the change
localized to the affected section and preserve the existing explanation of
RefGuard and UnitGuard.In
@docs/zh/design/symbol-index.md:
- Line 61: The fenced ASCII diagram in the index hierarchy section is missing a
language identifier, which triggers markdownlint MD040. Update the code block
that contains the three-level hierarchy diagram to use the text language tag so
the markdown renderer recognizes it properly; this is the block near the index
hierarchy content in symbol-index.md.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro **Run ID**: `fd300023-387e-452a-8721-6b09369f7fac` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between ab042480e02a4d4de9363262bc547323fe228d1d and d0bb54b81656638a47c04a263da1699e56aa01d0. </details> <details> <summary>📒 Files selected for processing (24)</summary> * `docs/en/design/command-resolve.md` * `docs/en/design/command.md` * `docs/en/design/compilation-context.md` * `docs/en/design/incremental-parse.md` * `docs/en/design/incremental.md` * `docs/en/design/index-design.md` * `docs/en/design/module-graph.md` * `docs/en/design/module.md` * `docs/en/design/overview.md` * `docs/en/design/symbol-index.md` * `docs/en/sidebar.yaml` * `docs/zh/design/command-resolve.md` * `docs/zh/design/command.md` * `docs/zh/design/compilation-context.md` * `docs/zh/design/dependency-scanning.md` * `docs/zh/design/incremental-parse.md` * `docs/zh/design/incremental.md` * `docs/zh/design/index-design.md` * `docs/zh/design/module-graph.md` * `docs/zh/design/module.md` * `docs/zh/design/overview.md` * `docs/zh/design/symbol-index.md` * `docs/zh/design/template-resolver.md` * `docs/zh/sidebar.yaml` </details> <details> <summary>💤 Files with no reviewable changes (8)</summary> * docs/zh/design/index-design.md * docs/en/design/command.md * docs/zh/design/command.md * docs/zh/design/incremental.md * docs/en/design/module.md * docs/en/design/incremental.md * docs/zh/design/module.md * docs/en/design/index-design.md </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
- Rewrite feature cards on landing page with more specific descriptions - Unfold dev section in sidebar (remove collapsed: true)
1 participant
Summary
Test plan