feat(candid): preserve doc comments on exported types and fields#707
Merged
Conversation
### Solution - Add `TypeDoc`, `FieldDoc`, and `TypeDocs` types to carry doc metadata alongside the type graph - Extend `CandidType` derive to extract Rust doc comments via new `_ty_doc()` hook; store per-TypeId in thread-local DOC_ENV - Update pretty-printer to render docs above type definitions, record fields, and variant members ### Details - Docs flow through `TypeContainer` which maps Rust TypeId docs to final Candid export names - Tuples with field docs fall back to explicit numeric field syntax ### Meta - updated tests accordingly
Click to see raw report |
There was a problem hiding this comment.
Pull request overview
This PR adds support for preserving Rust doc comments on exported Candid types and their fields/variants when generating .did files. Currently, doc comments are only preserved for service methods but not for data types defined via #[derive(CandidType)].
Changes:
- Introduces
TypeDoc,FieldDoc, andTypeDocstypes to carry doc metadata alongside the type graph, with a parallel metadata flow through thread-localDOC_ENVstorage andTypeContainer - Extends the
CandidTypederive macro to extract Rust doc comments via a new_ty_doc()trait hook, and refactorsextract_doc_commentsinto a shareddocsmodule - Updates the pretty-printer to render doc comments above type definitions, record fields, and variant members, with a tuple fallback to explicit numeric fields when tuple members carry docs
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| spec/Type-doc-comments.md | Design document describing the motivation, approach, alternatives, and properties of the feature |
| rust/candid_derive/src/docs.rs | Shared extract_doc_comments helper extracted from func.rs |
| rust/candid_derive/src/lib.rs | Registers the new docs module |
| rust/candid_derive/src/derive.rs | Extends CandidType derive to extract and emit doc metadata for structs, enums, fields, and variants |
| rust/candid_derive/src/func.rs | Uses shared doc extractor; wires TypeDocs from TypeContainer into DocComments at export time |
| rust/candid/src/types/mod.rs | Adds _ty_doc() default method to CandidType trait; calls env_doc during type registration |
| rust/candid/src/types/internal.rs | Defines TypeDoc, FieldDoc, TypeDocs; extends TypeContainer with doc association; adds DOC_ENV thread-local |
| rust/candid/src/pretty/candid.rs | Adds doc-aware pretty-printing for types and fields; extends DocComments with type def support |
| rust/candid/tests/types.rs | End-to-end tests for doc comments on types/fields/variants and round-trip parsing verification |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
…ith_doc Reuse the already-computed `id` in `CandidType::ty()` instead of calling `Self::id()` again for `env_doc`. Refactor `pp_ty_with_doc` to delegate non-Record/Variant arms to `pp_ty_inner`, removing ~25 lines of duplication. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
lwshang
approved these changes
Mar 15, 2026
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.
Solution
TypeDoc,FieldDoc, andTypeDocstypes to carry doc metadata alongside the type graphCandidTypederive to extract Rust doc comments via new_ty_doc()hook; store per-TypeId in thread-local DOC_ENVDetails
TypeContainerwhich maps Rust TypeId docs to final Candid export namesMeta