Document ISOSDacInterface private DAC APIs used by ClrMD - #55194
Open
leculver wants to merge 3 commits into
Open
Document ISOSDacInterface private DAC APIs used by ClrMD#55194leculver wants to merge 3 commits into
leculver wants to merge 3 commits into
Conversation
Adds reference documentation for the private DAC (mscordacwks.dll) APIs that ClrMD consumes on the desktop .NET Framework surface, so that consumers such as Visual Studio can rely on documented interfaces. - 52 new ISOSDacInterface method pages (the subset ClrMD calls) - 28 new Dacp* structure pages and 3 enumeration pages referenced by those methods - Fills 3 IXCLRData* gaps missed by dotnet#41675: IXCLRDataProcess::Flush, IXCLRDataModule::GetName, IXCLRDataStackWalk::GetContext - Expands the ISOSDacInterface interface method table, updates the debugging structures/enumerations indexes and the affected IXCLRData* interface pages, and registers every new page in toc.yml All new pages follow the existing IXCLRData* style, include the prefer-ICorDebug (DBI) recommended note, and carry ai-usage: ai-assisted frontmatter per repo guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 81f6c22d-7539-4637-9117-2454688f8441
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds new unmanaged debugging API reference documentation for additional SOS DAC (ISOSDacInterface) methods and related transport structures/enumerations, and wires them into the debugging docs navigation.
Changes:
- Added new API reference pages for multiple
ISOSDacInterface,IXCLRDataProcess,IXCLRDataModule, andIXCLRDataStackWalkmethods. - Added new DAC transport structures/enumerations docs (for GC, threads, domain/module data, RCW/CCW, etc.).
- Updated TOC and enumeration/structure index pages to include the new topics.
Show a summary per file
| File | Description |
|---|---|
| docs/framework/unmanaged-api/debugging/toc.yml | Adds TOC entries for the newly documented methods/structures/enumerations. |
| docs/framework/unmanaged-api/debugging/isosdacinterface-interface.md | Expands method listing to link to newly added method reference pages. |
| docs/framework/unmanaged-api/debugging/debugging-structures.md | Adds links/descriptions for newly added DAC transport structures. |
| docs/framework/unmanaged-api/debugging/debugging-enumerations.md | Adds links/descriptions for newly added enumerations. |
| docs/framework/unmanaged-api/debugging/*.md (new) | Adds per-method / per-structure / per-enumeration API reference pages. |
Copilot's findings
Comments suppressed due to low confidence (3)
docs/framework/unmanaged-api/debugging/vcsheaptype-enumeration.md:1
- The C/C++ enum typedef syntax is invalid as written (it’s missing the typedef name after the closing brace). Update the snippet to a valid form, e.g.
typedef enum VCSHeapType { ... } VCSHeapType;orenum VCSHeapType { ... };, so readers can compile it as instructed.
docs/framework/unmanaged-api/debugging/modulemaptype-enumeration.md:1 - This
typedef enumdeclaration is also invalid C/C++ syntax (missing the typedef name after the closing brace). Please change it to a compilable declaration (same options as above) to match the guidance “define the enumeration as specified above.”
docs/framework/unmanaged-api/debugging/ixclrdatastackwalk-getcontext-method.md:1 - Front-matter metadata keys are inconsistent across the new docs in this PR: some pages use
api_name/api_location/api_typeandf1_keywords/helpviewer_keywords, while these method pages use dotted keys likeapi.nameandf1.keywords. Align these keys with the schema used elsewhere in this doc set to avoid broken indexing/search/validation during doc build.
- Files reviewed: 93/93 changed files
- Comments generated: 5
- Resolve markdownlint failures (MD012 multiple blank lines, MD010 hard tabs) - Fix invalid C++ enum syntax in modulemaptype/vcsheaptype (add trailing typedef name) - Correct copied source-comment issues: "disply"->"display" (DacpFieldDescData), "DacpGcHeapDat"->"DacpGcHeapData" (DacpGcHeapDetails), remove internal TODO (DacpThreadpoolData), reconcile Request-helper comments (DacpThreadLocalModuleData, DacpDomainLocalModuleData) - Document ISOSDacInterface::GetDomainLocalModuleData (referenced by DacpDomainLocalModuleData's Request helper) and wire it into the interface table and TOC Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 81f6c22d-7539-4637-9117-2454688f8441
…e pages Adds "See also" cross-links between sibling methods within the same API family (MethodDesc, MethodTable, AppDomain/Assembly, Thread, Module, GC heap, OOM, heap-analyze, JIT/code, thread pool, domain/thread-local storage, RCW/CCW, handles/roots, sync block, loader heaps, and the IXCLRDataStackWalk/Module gap-fill methods), matching the prevailing convention in the existing IXCLRData* documentation. 126 cross-links across 50 pages. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 81f6c22d-7539-4637-9117-2454688f8441
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.
Adds reference documentation for the private DAC (mscordacwks.dll) APIs that ClrMD consumes on the desktop .NET Framework surface, so that consumers of ClrMD can be assured every API it takes a dependency on is either documented, or open source.
All new pages follow the existing IXCLRData* style, include the prefer-ICorDebug (DBI) recommended note, and carry ai-usage: ai-assisted frontmatter per repo guidance.
Internal previews
Toggle expand/collapse
Note
This table shows the first 30 preview links (sorted alphabetically by file path) found in the OPS build report. For the full list, select OpenPublishing.Build Details within checks.