feat(candid): preserve doc comments on exported types and fields by sasa-tomic · Pull Request #707 · dfinity/candid

sasa-tomic · 2026-03-13T08:07:59Z

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

This is needed for my work on Immutable Object Storage. I currently have some hacks to add doc comments to .did files, but everyone would benefit if this was fixed properly.

### 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

github-actions · 2026-03-13T08:13:01Z

Name	Max Mem (Kb)	Encode	Decode
blob	4_224	4_207_682 ($\textcolor{red}{0.03\%}$)	2_122_432 ($\textcolor{red}{0.00\%}$)
btreemap	75_456	4_735_768_625 ($\textcolor{red}{0.00\%}$)	15_227_605_589 ($\textcolor{green}{-0.33\%}$)
nns	192 ($\textcolor{red}{50.00\%}$)	2_027_272 ($\textcolor{green}{-0.26\%}$)	5_731_490 ($\textcolor{red}{2.83\%}$)
nns_list_proposal	1_216 ($\textcolor{red}{11.76\%}$)	7_048_445 ($\textcolor{red}{3.04\%}$)	67_866_962 ($\textcolor{green}{-1.38\%}$)
option_list	128	8_080_150 ($\textcolor{red}{0.05\%}$)	26_641_161 ($\textcolor{green}{-1.42\%}$)
text	6_336	4_204_523 ($\textcolor{red}{0.03\%}$)	7_877_775 ($\textcolor{green}{-0.00\%}$)
variant_list	128	8_133_077 ($\textcolor{red}{0.04\%}$)	25_274_351 ($\textcolor{green}{-0.84\%}$)
vec_int16	16_704	123_694_598 ($\textcolor{red}{0.00\%}$)	1_015_045_665 ($\textcolor{green}{-4.72\%}$)

Parser cost: 17_071_925 ($\textcolor{red}{0.00\%}$)
Extra args: 3_416_347 ($\textcolor{green}{-0.34\%}$)

Click to see raw report

---------------------------------------------------

Benchmark: blob
  total:
    instructions: 6.33 M (0.02%) (change within noise threshold)
    heap_increase: 66 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 4.21 M (0.03%) (change within noise threshold)
    heap_increase: 66 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 2.12 M (0.00%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: btreemap
  total:
    instructions: 19.96 B (-0.25%) (change within noise threshold)
    heap_increase: 1179 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 4.74 B (0.00%) (change within noise threshold)
    heap_increase: 159 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 15.23 B (-0.33%) (change within noise threshold)
    heap_increase: 1020 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: extra_args
  total:
    instructions: 3.42 M (-0.34%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: nns
  total:
    instructions: 25.67 M (0.60%) (change within noise threshold)
    heap_increase: 3 pages (regressed by 50.00%)
    stable_memory_increase: 0 pages (no change)

  0. Parsing (scope):
    calls: 1 (no change)
    instructions: 17.07 M (0.00%) (change within noise threshold)
    heap_increase: 3 pages (regressed by 50.00%)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 2.03 M (-0.26%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 5.73 M (regressed by 2.83%)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: nns_list_proposal
  total:
    instructions: 74.92 M (-0.98%) (change within noise threshold)
    heap_increase: 19 pages (regressed by 11.76%)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 7.05 M (regressed by 3.04%)
    heap_increase: 5 pages (regressed by 66.67%)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 67.87 M (-1.38%) (change within noise threshold)
    heap_increase: 14 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: option_list
  total:
    instructions: 34.72 M (-1.09%) (change within noise threshold)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 8.08 M (0.05%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 26.64 M (-1.42%) (change within noise threshold)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: text
  total:
    instructions: 12.08 M (0.01%) (change within noise threshold)
    heap_increase: 99 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 4.20 M (0.03%) (change within noise threshold)
    heap_increase: 66 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 7.88 M (-0.00%) (change within noise threshold)
    heap_increase: 33 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: variant_list
  total:
    instructions: 33.41 M (-0.63%) (change within noise threshold)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 8.13 M (0.04%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 25.27 M (-0.84%) (change within noise threshold)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: vec_int16
  total:
    instructions: 1.14 B (improved by 4.23%)
    heap_increase: 261 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 123.69 M (0.00%) (change within noise threshold)
    heap_increase: 261 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 1.02 B (improved by 4.72%)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Summary:
  instructions:
    status:   Improvements detected 🟢
    counts:   [total 9 | regressed 0 | improved 1 | new 0 | unchanged 8]
    change:   [max +152.51K | p75 +1.17K | median -210.17K | p25 -740.72K | min -50.33M]
    change %: [max +0.60% | p75 0.01% | median -0.34% | p25 -0.98% | min -4.23%]

  heap_increase:
    status:   Regressions detected 🔴
    counts:   [total 9 | regressed 2 | improved 0 | new 0 | unchanged 7]
    change:   [max +2 | p75 0 | median 0 | p25 0 | min 0]
    change %: [max +50.00% | p75 0.00% | median 0.00% | p25 0.00% | min 0.00%]

  stable_memory_increase:
    status:   No significant changes 👍
    counts:   [total 9 | regressed 0 | improved 0 | new 0 | unchanged 9]
    change:   [max 0 | p75 0 | median 0 | p25 0 | min 0]
    change %: [max 0.00% | p75 0.00% | median 0.00% | p25 0.00% | min 0.00%]

---------------------------------------------------

Only significant changes:
| status | name                           | calls |    ins |  ins Δ% |  HI |   HI Δ% | SMI |  SMI Δ% |
|--------|--------------------------------|-------|--------|---------|-----|---------|-----|---------|
|   +    | nns_list_proposal::1. Encoding |     1 |  7.05M |  +3.04% |   5 | +66.67% |   0 |   0.00% |
|   +    | nns::2. Decoding               |     1 |  5.73M |  +2.83% |   0 |   0.00% |   0 |   0.00% |
|   +    | nns                            |       | 25.67M |  +0.60% |   3 | +50.00% |   0 |   0.00% |
|   +    | nns::0. Parsing                |     1 | 17.07M |   0.00% |   3 | +50.00% |   0 |   0.00% |
|   +    | nns_list_proposal              |       | 74.92M |  -0.98% |  19 | +11.76% |   0 |   0.00% |
|   -    | vec_int16                      |       |  1.14B |  -4.23% | 261 |   0.00% |   0 |   0.00% |
|   -    | vec_int16::2. Decoding         |     1 |  1.02B |  -4.72% |   0 |   0.00% |   0 |   0.00% |

ins = instructions, HI = heap_increase, SMI = stable_memory_increase, Δ% = percent change

---------------------------------------------------
Successfully persisted results to canbench_results.yml

sasa-tomic self-assigned this Mar 13, 2026

sasa-tomic marked this pull request as ready for review March 13, 2026 08:09

sasa-tomic requested a review from a team as a code owner March 13, 2026 08:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(candid): preserve doc comments on exported types and fields#707

feat(candid): preserve doc comments on exported types and fields#707
sasa-tomic wants to merge 1 commit intomasterfrom
feat/type-doc-comments

sasa-tomic commented Mar 13, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

sasa-tomic commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Solution

Details

Meta

Uh oh!

github-actions bot commented Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

sasa-tomic commented Mar 13, 2026 •

edited

Loading