docs: design documentation and API doc comments - #410
Closed
16bit-ykiko wants to merge 5 commits into
Closed
Conversation
Design docs (docs/en/design/): - Rewrite architecture.md: multi-process model, Workspace/Session state, component responsibilities, message flow, async model - Rewrite compilation.md: pull-based compilation, PCH content-addressing, two-layer staleness detection, persistent cache, generation counter - New dependency-scan.md: wave-based BFS algorithm, caching strategy, DependencyGraph output - Update header-context.md: protocol API, automatic resolution, preamble injection, caching - Update template-resolver.md: PseudoInstantiator/SubstituteOnly phases, lookup mechanism, caching - Write index.md: TUIndex/ProjectIndex/MergedIndex hierarchy, dual-source queries, background indexing, persistence Header doc comments (/// Doxygen): - feature.h: all 10 feature function declarations - tu_index.h: module doc + struct/method docs - project_index.h: module doc + merge/serialize/from docs - worker_pool.h, merged_index.h, dependency_graph.h, command.h, semantic_visitor.h: module-level doc comments Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis PR adds and expands design documentation and file-level API docstrings across the repo, specifying a multi-process MasterServer/WorkerPool architecture, pull-based compilation, wave-based dependency scanning, multi-layer indexing, header-context protocol, and template-resolver semantics. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant MasterServer
participant Workspace
participant WorkerPool
participant Worker
Client->>MasterServer: HoverRequest(file, offset, gen?)
MasterServer->>Workspace: ensure_session(file) / read Session (generation, dirty)
MasterServer->>MasterServer: check if up-to-date (gen match, cached result)
alt cached & up-to-date
MasterServer->>Client: HoverResponse(cached_result)
else needs compile
MasterServer->>WorkerPool: schedule detached_compile(task{file, gen, deps_snapshot})
WorkerPool->>Worker: compile_request (stateful / with path-affinity)
Worker-->>WorkerPool: compile_result (gen, diagnostics, artifacts)
WorkerPool->>MasterServer: relay_compile_result
MasterServer->>Workspace: verify session generation still equals result.gen
alt generation matches
MasterServer->>Client: HoverResponse(result)
else mismatch
MasterServer->>Client: HoverResponse(empty / retry_suggestion)
end
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 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 |
- Rename index.md → indexing.md (avoids VitePress index page conflict) - New index.md as directory overview with document table + source layout - Expand architecture.md ASCII diagram to show Workspace/Session contents, Compiler/Indexer APIs, and worker responsibilities Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Move design overview page to dev/source-layout.md (better fit) - Rename indexing.md back to index.md (symbol index design doc) - Fix links to use absolute paths from dev/ to design/ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/en/design/dependency-scan.md (1)
17-23: Add a language tag to the fenced block to satisfy markdownlint.At Line 17, the code fence is missing a language identifier (MD040). Use
textfor this pseudo-format block.Proposed fix
-``` +```text Wave 0: All source files from the CDB Wave 1: Headers discovered via `#include` in wave 0 Wave 2: Headers discovered via `#include` in wave 1 ... Wave N: No new files discovered -> done</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/en/design/dependency-scan.mdaround lines 17 - 23, The fenced code
block showing the "Wave 0...Wave N" sequence in
docs/en/design/dependency-scan.md is missing a language tag causing markdownlint
MD040; update the opening fence for that block fromtotext so the block
becomes a labeled text code fence (leave the content unchanged and keep the
closing ``` intact).</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In@docs/en/design/dependency-scan.md:
- Around line 17-23: The fenced code block showing the "Wave 0...Wave N"
sequence in docs/en/design/dependency-scan.md is missing a language tag causing
markdownlint MD040; update the opening fence for that block fromtotext
so the block becomes a labeled text code fence (leave the content unchanged and
keep the closing ``` intact).</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro **Run ID**: `7200b89d-abe8-488d-b563-0fe8431cd7b3` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 8b3e3a95954b3af7638241ee8ec9381936791048 and 79a9eb02773505f2bc61d37173d29186c7baf5f7. </details> <details> <summary>📒 Files selected for processing (14)</summary> * `docs/en/design/architecture.md` * `docs/en/design/compilation.md` * `docs/en/design/dependency-scan.md` * `docs/en/design/header-context.md` * `docs/en/design/index.md` * `docs/en/design/template-resolver.md` * `src/command/command.h` * `src/feature/feature.h` * `src/index/merged_index.h` * `src/index/project_index.h` * `src/index/tu_index.h` * `src/semantic/semantic_visitor.h` * `src/server/worker_pool.h` * `src/syntax/dependency_graph.h` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Design docs should describe concepts and behavior, not list specific API signatures. Replace Class::method() references with plain-English descriptions throughout architecture, compilation, dependency-scan, header-context, template-resolver, and index docs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/en/design/architecture.md`:
- Around line 7-44: The fenced diagram block in docs/en/design/architecture.md
is unlabeled (starts with ```) which triggers MD040; change the opening fence to
include a language hint (e.g., ```text) so the block becomes ```text ... ```,
ensuring the ASCII diagram is rendered consistently by markdown linters and
renderers; locate the triple-backtick fenced diagram block in the file and
update its opening fence to include the "text" language hint.
In `@docs/en/design/compilation.md`:
- Around line 9-13: Add explicit language tags to the two unlabeled fenced code
blocks in the document so markdown linters stop flagging MD040: change the first
triple-fence before the lines "didOpen / didChange --> update buffer text,
increment generation, mark AST dirty ..." to use ```text and change the second
triple-fence around ".clice/cache/pch/{hash:016x}.pch" to use ```text as well so
both blocks are labeled for tooling.
In `@docs/en/design/dependency-scan.md`:
- Around line 17-23: The fenced code block showing "Wave 0...Wave N" is missing
a language label; update the unlabeled triple-backtick block in
docs/en/design/dependency-scan.md to include a language identifier (e.g., add
```text) so the example is a labeled fenced code block; ensure the opening fence
before the "Wave 0" line is changed from ``` to ```text and the closing fence
remains ``` to fix the MD040 lint warning.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: a38d9b16-c4c2-4961-bc0b-ee80774cfae9
📒 Files selected for processing (6)
docs/en/design/architecture.mddocs/en/design/compilation.mddocs/en/design/dependency-scan.mddocs/en/design/header-context.mddocs/en/design/index.mddocs/en/design/template-resolver.md
✅ Files skipped from review due to trivial changes (1)
- docs/en/design/index.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/en/design/header-context.md
- docs/en/design/template-resolver.md
Comment on lines
+7
to
+44
| ``` | ||
| Editor (LSP client) | ||
| | | ||
| JSON-RPC (stdin/stdout) | ||
| | | ||
| +---------------------- | -----------------------+ | ||
| | MasterServer | | ||
| | | | ||
| | Workspace (project-level, persistent) | | ||
| | ┌───────────────────────────────────────┐ | | ||
| | │ CDB, DependencyGraph, CompileGraph │ | | ||
| | │ PCH/PCM cache, ProjectIndex, PathPool │ | | ||
| | └───────────────────────────────────────┘ | | ||
| | | | ||
| | Sessions (per-file, volatile) | | ||
| | ┌───────────────────────────────────────┐ | | ||
| | │ buffer text, AST state, deps snapshot │ | | ||
| | │ PCH ref, header context, file index │ | | ||
| | └───────────────────────────────────────┘ | | ||
| | | | ||
| | Compiler Indexer | | ||
| | | | | | ||
| +--------|----------------------|-----------------+ | ||
| | | | ||
| Bincode IPC (pipes) Bincode IPC (pipes) | ||
| | | | ||
| ┌───────┴───────┐ ┌───────┴───────┐ | ||
| │ Stateful │ │ Stateless │ | ||
| │ Workers │ │ Workers │ | ||
| │ │ │ │ | ||
| │ Hold ASTs │ │ One-shot: │ | ||
| │ Path-affinity │ │ PCH/PCM │ | ||
| │ LRU eviction │ │ Completion │ | ||
| │ │ │ Sig. help │ | ||
| │ Queries run │ │ │ | ||
| │ against AST │ │ Round-robin │ | ||
| └───────────────┘ └───────────────┘ | ||
| ``` |
There was a problem hiding this comment.
Add a language hint to the fenced diagram block.
Line 7 starts an unlabeled fenced block; this can trigger MD040 and reduce renderer/tooling consistency.
💡 Suggested markdown fix
-```
+```text
Editor (LSP client)
|
JSON-RPC (stdin/stdout)
|
+---------------------- | -----------------------+
| MasterServer |
| |
| Workspace (project-level, persistent) |
| ┌───────────────────────────────────────┐ |
| │ CDB, DependencyGraph, CompileGraph │ |
| │ PCH/PCM cache, ProjectIndex, PathPool │ |
| └───────────────────────────────────────┘ |
| |
| Sessions (per-file, volatile) |
| ┌───────────────────────────────────────┐ |
| │ buffer text, AST state, deps snapshot │ |
| │ PCH ref, header context, file index │ |
| └───────────────────────────────────────┘ |
| |
| Compiler Indexer |
| | | |
+--------|----------------------|-----------------+
| |
Bincode IPC (pipes) Bincode IPC (pipes)
| |
┌───────┴───────┐ ┌───────┴───────┐
│ Stateful │ │ Stateless │
│ Workers │ │ Workers │
│ │ │ │
│ Hold ASTs │ │ One-shot: │
│ Path-affinity │ │ PCH/PCM │
│ LRU eviction │ │ Completion │
│ │ │ Sig. help │
│ Queries run │ │ │
│ against AST │ │ Round-robin │
└───────────────┘ └───────────────┘</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/en/design/architecture.md` around lines 7 - 44, The fenced diagram block
in docs/en/design/architecture.md is unlabeled (starts with ```) which triggers
MD040; change the opening fence to include a language hint (e.g., ```text) so
the block becomes ```text ... ```, ensuring the ASCII diagram is rendered
consistently by markdown linters and renderers; locate the triple-backtick
fenced diagram block in the file and update its opening fence to include the
"text" language hint.
Comment on lines
+9
to
+13
| ``` | ||
| didOpen / didChange --> update buffer text, increment generation, mark AST dirty | ||
| didSave --> cascade invalidation via Workspace, mark dependents dirty | ||
| feature request --> ensure compiled --> compile if dirty --> serve query | ||
| ``` |
There was a problem hiding this comment.
Add language tags to fenced blocks for markdown lint/tooling compatibility.
Lines 9 and 35 start unlabeled fences, which can trigger MD040.
💡 Suggested markdown fix
-```
+```text
didOpen / didChange --> update buffer text, increment generation, mark AST dirty
didSave --> cascade invalidation via Workspace, mark dependents dirty
feature request --> ensure compiled --> compile if dirty --> serve query...
- +text
.clice/cache/pch/{hash:016x}.pch
Also applies to: 35-37
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/en/design/compilation.md` around lines 9 - 13, Add explicit language
tags to the two unlabeled fenced code blocks in the document so markdown linters
stop flagging MD040: change the first triple-fence before the lines "didOpen /
didChange --> update buffer text, increment generation, mark AST dirty ..." to
use ```text and change the second triple-fence around
".clice/cache/pch/{hash:016x}.pch" to use ```text as well so both blocks are
labeled for tooling.
Comment on lines
+17
to
+23
| ``` | ||
| Wave 0: All source files from the CDB | ||
| Wave 1: Headers discovered via #include in wave 0 | ||
| Wave 2: Headers discovered via #include in wave 1 | ||
| ... | ||
| Wave N: No new files discovered -> done | ||
| ``` |
There was a problem hiding this comment.
Specify a language for the fenced wave example.
Line 17 opens an unlabeled code fence (MD040).
💡 Suggested markdown fix
-```
+```text
Wave 0: All source files from the CDB
Wave 1: Headers discovered via `#include` in wave 0
Wave 2: Headers discovered via `#include` in wave 1
...
Wave N: No new files discovered -> done</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 17-17: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/en/design/dependency-scan.md` around lines 17 - 23, The fenced code
block showing "Wave 0...Wave N" is missing a language label; update the
unlabeled triple-backtick block in docs/en/design/dependency-scan.md to include
a language identifier (e.g., add ```text) so the example is a labeled fenced
code block; ensure the opening fence before the "Wave 0" line is changed from
``` to ```text and the closing fence remains ``` to fix the MD040 lint warning.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
architecture.md: multi-process model, Workspace/Session state, component responsibilities, message flow, async modelcompilation.md: pull-based compilation, PCH content-addressing, two-layer staleness detection, persistent cache, generation counterdependency-scan.md: wave-based BFS algorithm, caching strategy, DependencyGraph outputheader-context.md: protocol API, automatic resolution, preamble injection, cachingtemplate-resolver.md: PseudoInstantiator/SubstituteOnly phases, lookup mechanism, cachingindex.mdfrom scratch: TUIndex/ProjectIndex/MergedIndex hierarchy, dual-source queries, background indexing, persistence///doc comments tofeature.h(all 10 feature functions),tu_index.h,project_index.h(module + struct + method docs), and module-level docs toworker_pool.h,merged_index.h,dependency_graph.h,command.h,semantic_visitor.hTest plan
cmake --buildpasses (comments only, no code changes)pixi run formatclean🤖 Generated with Claude Code
Summary by CodeRabbit