Improve CoreCLR design docs for AI-agent navigation#125552
Draft
AaronRobinsonMSFT wants to merge 2 commits intodotnet:mainfrom
Draft
Improve CoreCLR design docs for AI-agent navigation#125552AaronRobinsonMSFT wants to merge 2 commits intodotnet:mainfrom
AaronRobinsonMSFT wants to merge 2 commits intodotnet:mainfrom
Conversation
Add explicit source file path tables and entry points to major BOTR and JIT design documents so AI agents can map concepts to actual files. Changes: - Create INDEX.md: master topic→doc→source mapping with directory map and key entry points table - Create profiling/README.md: index profiling docs, mark blog archive as historical, add source file table - type-system.md: replace informal file list with full path table and entry point table with exact file locations - garbage-collection.md: add Key Source Files section with GC heap, allocation helpers, and frozen object heap paths - threading.md: fix relative path to absolute URL, add source file table for Thread/ThreadStore/ThreadSuspend - exceptions.md: add source file table for EX_TRY macros, COMPlusThrow, and exception handling infrastructure - stackwalking.md: add source file table for stack walker, CrawlFrame, and Frame types - method-descriptor.md: add source file table for MethodDesc and precode - type-loader.md: add source file table for ClassLoader and MethodTableBuilder - virtual-stub-dispatch.md: fix old clr/src/vm/ display text in links, replace prose with structured file table - ryujit-overview.md: fix 6 old-format paths (src/jit/→src/coreclr/jit/ etc.), add comprehensive Key Source Files table covering all major JIT subsystems - lsra-detail.md: add source file table for LSRA implementation files - first-class-structs.md: add reference to promotion.cpp and related files All 40+ file path references verified against current source tree. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves CoreCLR design-document navigation by adding structured “key source files”/entry-point tables and a central index so readers (and tooling/agents) can map concepts directly to the current source tree.
Changes:
- Added
docs/design/coreclr/INDEX.mdto map major CoreCLR topics to design docs, source directories, and key entry points. - Added “Key Source Files” (and in some cases “Key entry points”) sections across several BOTR and JIT design docs.
- Fixed/modernized a handful of file path references (e.g., older
src/jit-style paths, outdated display text).
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/design/coreclr/INDEX.md | New master index mapping topics → docs → primary sources and entry points |
| docs/design/coreclr/profiling/README.md | New profiling-doc index + key runtime source file table |
| docs/design/coreclr/jit/ryujit-overview.md | Updates legacy paths and adds comprehensive JIT “Key Source Files” table |
| docs/design/coreclr/jit/lsra-detail.md | Adds LSRA source file table and entry point |
| docs/design/coreclr/jit/first-class-structs.md | Adds pointers to struct-promotion and related JIT sources |
| docs/design/coreclr/botr/virtual-stub-dispatch.md | Replaces prose links with structured key-source-files table + entry point |
| docs/design/coreclr/botr/type-system.md | Replaces informal file list with full tables (components + entry points) |
| docs/design/coreclr/botr/type-loader.md | Adds ClassLoader/MTB source file table and entry point |
| docs/design/coreclr/botr/threading.md | Fixes threads.h link and adds thread/threadstore/suspend source table |
| docs/design/coreclr/botr/stackwalking.md | Adds stack-walking source file table and entry points |
| docs/design/coreclr/botr/method-descriptor.md | Adds MethodDesc/precode/stubmgr source file table |
| docs/design/coreclr/botr/garbage-collection.md | Adds GC/GC-helpers/FOH key source files and entry points |
| docs/design/coreclr/botr/exceptions.md | Adds EX_TRY/COMPlusThrow/exception infra source file table |
You can also share your feedback on Copilot code review. Take the survey.
- Use full repo-root-relative paths for all files (no bare filenames like `class.h` — always `src/coreclr/vm/class.h`) - Fix BuildMethodTable() → BuildMethodTableThrowing() (3 locations) - Fix ResolveWorkerStatic() → ResolveWorker() (3 locations) - Add gcheaputilities.cpp to GC source file table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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
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.
Add explicit source file path tables and entry points to major BOTR and JIT design documents so AI agents can map concepts to actual files.
Changes:
All 40+ file path references verified against current source tree.