feat: support doc comments in Rust bindings generation by ilbertt · Pull Request #637 · dfinity/candid

ilbertt · 2025-07-09T10:40:08Z

Overview
Adds support for doc comments in the Rust bindings generator.

Considerations
Not all doc comments are supported due to how the Rust code is nominalized, as you can notice from the rust/candid_parser/tests/assets/ok/example.rs as compared to the rust/candid_parser/tests/assets/ok/example.mo Motoko one.

github-actions · 2025-07-09T10:45:06Z

Name	Max Mem (Kb)	Encode	Decode
blob	4_224	4_206_559	2_121_055
btreemap	75_456	4_261_360_630	15_191_359_361
nns	192	1_966_454	5_468_145 ($\textcolor{red}{0.08\%}$)
nns_list_proposal	1_088	6_814_372 ($\textcolor{red}{0.00\%}$)	66_996_590 ($\textcolor{green}{-0.00\%}$)
option_list	128	7_481_063	25_531_164
text	6_336	4_203_506	7_877_219
variant_list	128	7_537_258 ($\textcolor{red}{0.00\%}$)	24_121_592 ($\textcolor{red}{0.35\%}$)
vec_int16	16_704	123_693_002	1_019_238_917

Parser cost: 15_218_738 ($\textcolor{red}{0.05\%}$)
Extra args: 3_165_441

Click to see raw report

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

Benchmark: blob
  total:
    instructions: 6.33 M (no change)
    heap_increase: 66 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 4.21 M (no change)
    heap_increase: 66 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 2.12 M (no change)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: text
  total:
    instructions: 12.08 M (no change)
    heap_increase: 99 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 4.20 M (no change)
    heap_increase: 66 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 7.88 M (no change)
    heap_increase: 33 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

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

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 123.69 M (no change)
    heap_increase: 261 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

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

Benchmark: btreemap
  total:
    instructions: 19.45 B (no change)
    heap_increase: 1179 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 4.26 B (no change)
    heap_increase: 159 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 15.19 B (no change)
    heap_increase: 1020 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: option_list
  total:
    instructions: 33.01 M (no change)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 7.48 M (no change)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    calls: 1 (no change)
    instructions: 25.53 M (no change)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: variant_list
  total:
    instructions: 31.66 M (0.27%) (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: 7.54 M (0.00%) (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: 24.12 M (0.35%) (change within noise threshold)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: nns
  total:
    instructions: 23.50 M (0.05%) (change within noise threshold)
    heap_increase: 3 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 1.97 M (no change)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

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

Benchmark: nns_list_proposal
  total:
    instructions: 73.81 M (0.00%) (change within noise threshold)
    heap_increase: 17 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

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

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

Benchmark: extra_args
  total:
    instructions: 3.17 M (no change)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Summary:
  instructions:
    status:   No significant changes 👍
    counts:   [total 9 | regressed 0 | improved 0 | new 0 | unchanged 9]
    change:   [max +84.33K | p75 +115 | median 0 | p25 0 | min 0]
    change %: [max +0.27% | p75 0.00% | median 0.00% | p25 0.00% | min 0.00%]

  heap_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%]

  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%]

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

…omments-rust

christoph-dfinity

The solution you came up with for normalization is unfortunately quadratic in the depth of the nesting.
You could get around that by either remembering a mapping from GeneratedName -> Vec<Path> and then having a function that resolves a Vec<Path> against IDLMergedProg, or GeneratedName -> &IDLType (notice the reference type).
That would also avoid modifying the merged prog with synthetic bindings, which I think would be cleaner.

christoph-dfinity

Very nice! Just one small nit.

Describes the changes from the following PRs: - #637 - #638 - #640 - #641

**Overview** Describes the changes from the following PRs: - #637 - #638 - #640 - #641

Describes the changes from the following PRs: - #637 - #638 - #640 - #641

**Overview** Describes the changes from the following PRs: - #637 - #638 - #640 - #641

ilbertt added 2 commits July 9, 2025 12:35

feat: support doc comments in Rust bindings generation

52ad7dc

refactor: remove redundant code

5c1e3c3

ilbertt added 7 commits July 9, 2025 12:46

refactor: remove redundant code

71d3808

refactor: remove redundant code

671dcb5

fix: use record fields in the variant

aa763b0

refactor: remove duplicated code

6f91d3b

refactor: remove pp_ty_rich

bfc88c6

refactor: remove method from syntax

b73298a

refactor: simplify pp_ty

17c3d23

ilbertt commented Jul 9, 2025

View reviewed changes

Comment thread rust/candid_parser/src/bindings/rust.rs

Merge remote-tracking branch 'origin/master' into luca/SDK-2209-doc-c…

ad70fd7

…omments-rust

ilbertt marked this pull request as ready for review July 9, 2025 13:28

ilbertt requested a review from a team as a code owner July 9, 2025 13:28

christoph-dfinity suggested changes Jul 9, 2025

View reviewed changes

Comment thread rust/candid_parser/src/bindings/rust.rs Outdated

Comment thread rust/candid_parser/src/bindings/rust.rs Outdated

Comment thread rust/candid/src/types/syntax.rs Outdated

ilbertt added 2 commits July 9, 2025 16:38

refactor: use map for generated types

ec2db4b

refactor: cleanup code

44ef74a

ilbertt requested a review from christoph-dfinity July 9, 2025 14:43

fix: support doc comments for all decs

fa2d308

ilbertt mentioned this pull request Jul 9, 2025

feat: support doc comments in TypeScript bindings generator #638

Merged

christoph-dfinity approved these changes Jul 10, 2025

View reviewed changes

Comment thread rust/candid_parser/src/bindings/rust.rs

ilbertt merged commit 8291f6d into master Jul 10, 2025
11 checks passed

ilbertt deleted the luca/SDK-2209-doc-comments-rust branch July 10, 2025 08:04

ilbertt added a commit that referenced this pull request Jul 14, 2025

chore: update changelog

f4de835

Describes the changes from the following PRs: - #637 - #638 - #640 - #641

ilbertt mentioned this pull request Jul 14, 2025

chore: update changelog #646

Merged

ilbertt added a commit that referenced this pull request Jul 14, 2025

chore: update changelog (#646)

8f0483c

**Overview** Describes the changes from the following PRs: - #637 - #638 - #640 - #641

ilbertt added a commit that referenced this pull request Jul 14, 2025

chore: update changelog

6769eac

Describes the changes from the following PRs: - #637 - #638 - #640 - #641

ilbertt mentioned this pull request Jul 14, 2025

chore: update changelog #647

Merged

ilbertt added a commit that referenced this pull request Jul 14, 2025

chore: update changelog (#647)

cb16726

**Overview** Describes the changes from the following PRs: - #637 - #638 - #640 - #641

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: support doc comments in Rust bindings generation#637

feat: support doc comments in Rust bindings generation#637
ilbertt merged 13 commits into
masterfrom
luca/SDK-2209-doc-comments-rust

ilbertt commented Jul 9, 2025

Uh oh!

github-actions Bot commented Jul 9, 2025 •

edited

Loading

Uh oh!

Uh oh!

christoph-dfinity left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

christoph-dfinity left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ilbertt commented Jul 9, 2025

Uh oh!

github-actions Bot commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

christoph-dfinity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

christoph-dfinity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Jul 9, 2025 •

edited

Loading