feat: support line comments #619

ilbertt · 2025-06-12T07:41:22Z

Overview
Adds support for line comments that are "associated" to types, fields and services in Candid. "Associated" means that there's no empty line between the last line of the comment and the underlying type, field or service.

Considerations
Still needs support for block comments.

github-actions · 2025-06-13T08:54:20Z

Name	Max Mem (Kb)	Encode	Decode
blob	4_224	20_459_864 ($\textcolor{red}{0.00\%}$)	12_084_069 ($\textcolor{red}{0.00\%}$)
btreemap	75_456	4_641_551_548 ($\textcolor{red}{0.00\%}$)	15_385_376_412 ($\textcolor{red}{0.42\%}$)
nns	192 ($\textcolor{red}{50.00\%}$)	2_105_963 ($\textcolor{red}{0.55\%}$)	5_774_359 ($\textcolor{red}{2.49\%}$)
nns_list_proposal	1_216 ($\textcolor{red}{11.76\%}$)	7_943_891 ($\textcolor{red}{2.19\%}$)	84_440_985 ($\textcolor{red}{4.70\%}$)
option_list	192 ($\textcolor{red}{50.00\%}$)	7_910_318 ($\textcolor{red}{0.01\%}$)	27_306_017 ($\textcolor{red}{3.80\%}$)
text	6_336	20_457_050 ($\textcolor{red}{0.00\%}$)	17_315_850 ($\textcolor{red}{0.00\%}$)
variant_list	192 ($\textcolor{red}{50.00\%}$)	7_904_219 ($\textcolor{green}{-0.73\%}$)	25_651_842 ($\textcolor{red}{4.39\%}$)
vec_int16	16_704	168_585_148 ($\textcolor{red}{0.00\%}$)	1_159_749_521 ($\textcolor{red}{5.74\%}$)

Parser cost: 18_080_849 ($\textcolor{red}{2.02\%}$)
Extra args: 3_495_822 ($\textcolor{red}{7.43\%}$)

Click to see raw report

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

Benchmark: blob
  total:
    instructions: 32.55 M (0.00%) (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: 20.46 M (0.00%) (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: 12.08 M (0.00%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: text
  total:
    instructions: 37.78 M (0.00%) (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: 20.46 M (0.00%) (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: 17.32 M (0.00%) (change within noise threshold)
    heap_increase: 33 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: vec_int16
  total:
    instructions: 1.33 B (regressed by 4.97%)
    heap_increase: 261 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 168.59 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.16 B (regressed by 5.74%)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: btreemap
  total:
    instructions: 20.03 B (0.32%) (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.64 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.39 B (0.42%) (change within noise threshold)
    heap_increase: 1020 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: option_list
  total:
    instructions: 35.22 M (regressed by 2.92%)
    heap_increase: 3 pages (regressed by 50.00%)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 7.91 M (0.01%) (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: 27.31 M (regressed by 3.80%)
    heap_increase: 3 pages (regressed by 50.00%)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: variant_list
  total:
    instructions: 33.56 M (regressed by 3.14%)
    heap_increase: 3 pages (regressed by 50.00%)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 7.90 M (-0.73%) (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.65 M (regressed by 4.39%)
    heap_increase: 3 pages (regressed by 50.00%)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: nns
  total:
    instructions: 26.82 M (regressed by 2.03%)
    heap_increase: 3 pages (regressed by 50.00%)
    stable_memory_increase: 0 pages (no change)

  0. Parsing (scope):
    calls: 1 (no change)
    instructions: 18.08 M (regressed by 2.02%)
    heap_increase: 3 pages (regressed by 50.00%)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    calls: 1 (no change)
    instructions: 2.11 M (0.55%) (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.77 M (regressed by 2.49%)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Benchmark: nns_list_proposal
  total:
    instructions: 92.39 M (regressed by 4.48%)
    heap_increase: 19 pages (regressed by 11.76%)
    stable_memory_increase: 0 pages (no change)

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

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

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

Benchmark: extra_args
  total:
    instructions: 3.50 M (regressed by 7.43%)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

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

Summary:
  instructions:
    status:   Regressions detected 🔴
    counts:   [total 9 | regressed 6 | improved 0 | new 0 | unchanged 3]
    change:   [max +64.21M | p75 +3.96M | median +999.26K | p25 +241.91K | min +680]
    change %: [max +7.43% | p75 +4.48% | median +2.92% | p25 +0.32% | min 0.00%]

  heap_increase:
    status:   Regressions detected 🔴
    counts:   [total 9 | regressed 4 | improved 0 | new 0 | unchanged 5]
    change:   [max +2 | p75 +1 | median 0 | p25 0 | min 0]
    change %: [max +50.00% | p75 +50.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 Δ% |
|--------|--------------------------------|-------|--------|---------|-----|---------|-----|---------|
|   +    | extra_args                     |       |  3.50M |  +7.43% |   0 |   0.00% |   0 |   0.00% |
|   +    | vec_int16::2. Decoding         |     1 |  1.16B |  +5.74% |   0 |   0.00% |   0 |   0.00% |
|   +    | vec_int16                      |       |  1.33B |  +4.97% | 261 |   0.00% |   0 |   0.00% |
|   +    | nns_list_proposal::2. Decoding |     1 | 84.44M |  +4.70% |  14 |   0.00% |   0 |   0.00% |
|   +    | nns_list_proposal              |       | 92.39M |  +4.48% |  19 | +11.76% |   0 |   0.00% |
|   +    | variant_list::2. Decoding      |     1 | 25.65M |  +4.39% |   3 | +50.00% |   0 |   0.00% |
|   +    | option_list::2. Decoding       |     1 | 27.31M |  +3.80% |   3 | +50.00% |   0 |   0.00% |
|   +    | variant_list                   |       | 33.56M |  +3.14% |   3 | +50.00% |   0 |   0.00% |
|   +    | option_list                    |       | 35.22M |  +2.92% |   3 | +50.00% |   0 |   0.00% |
|   +    | nns::2. Decoding               |     1 |  5.77M |  +2.49% |   0 |   0.00% |   0 |   0.00% |
|   +    | nns_list_proposal::1. Encoding |     1 |  7.94M |  +2.19% |   5 | +66.67% |   0 |   0.00% |
|   +    | nns                            |       | 26.82M |  +2.03% |   3 | +50.00% |   0 |   0.00% |
|   +    | nns::0. Parsing                |     1 | 18.08M |  +2.02% |   3 | +50.00% |   0 |   0.00% |

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

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

christoph-dfinity · 2025-06-17T09:33:53Z

Summarizing our pairing session from this morning:

Approach using the side table for documentation comments from wip: lex documentation comments, and attach them to declarations #621 does what we need to do for parsing
Currently codegen uses candid::compile which pretty prints the semantic representation (candid/src/types/internal.rs) rather than the syntactic representation (candid_parser/src/types.rs). This is problematic in a few ways (eg. it loses the distinction between vec nat8 and blob), but it also means to print the documentation comments we need to cram then into the semantic types or store them off to the side somehow.
I suggested exploring if we can make the code generators produce the syntactic representation, and Luca said he's going to spend some time looking into that.

crusso · 2025-06-17T09:44:21Z

FTR, I drafted this PR a while ago to preserve source vec nat8 and blob #537

ilbertt · 2025-06-17T10:05:51Z

@christoph-dfinity @crusso it doesn't look that hard to use the IDL* types inside the candid_parser. This allows use to bring comments around pretty easily.
Here's how I've changed the motoko bindgen: https://github.com/dfinity/candid/compare/luca/use-idl-types-in-parser

One problem I see is that we would need to pull the candid_parser as a dependency inside the candid and candid_derive crates, in order to use the IDL* types.

christoph-dfinity · 2025-06-17T10:36:56Z

One problem I see is that we would need to pull the candid_parser as a dependency inside the candid and candid_derive crates, in order to use the IDL* types.

Hmm I see... I think I'd prefer moving the IDL* types into the candid crate (assuming that's the one at the "bottom" of the hierarchy)

ilbertt added 13 commits June 11, 2025 18:45

feat: support line comments (wip)

679ddac

Merge remote-tracking branch 'origin/master' into luca/support-comments

d261a5a

feat: support comments in TS bindings

1c99b85

fix: typo

f47cbb6

test: add comments to parse_idl_prog

f439fe0

feat: support comments in rust bindgen

f5c2682

feat: support line comments for actors

0083427

Merge remote-tracking branch 'origin/master' into luca/support-comments

aa636db

fix: do not prepend comments in inner types

9823791

fix: support multi-line comments, even nested

ee0222d

feat: support comments from rust

705f603

test: fix comments

1ae40e6

fix: use Rc for comment

0386630

ilbertt added 4 commits June 13, 2025 11:04

refactor: remove unused code

3e97d94

refactor: move comment lines around instead of the entire comment string

f73994a

refactor: remove unnecessary types

5d9d8b8

refactor: remove unnecessary code

c0c974d

ilbertt changed the title ~~feat: support comments~~ feat: support line comments Jun 13, 2025

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

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

ilbertt added 2 commits June 13, 2025 16:05

refactor: constants

57b40ab

refactor: remove unnecessary escape chars

688cabb

ilbertt marked this pull request as draft June 13, 2025 16:25

fix: ignore line comments at the end of the line

2451fcc

ilbertt marked this pull request as ready for review June 16, 2025 12:46

ilbertt added 2 commits June 16, 2025 14:59

fix: do not ignore comments at the start of the file

d65a184

fix: ignore indented isolated comments

e68d8ea

ilbertt mentioned this pull request Jun 16, 2025

feat: support block comments #620

Closed

ilbertt marked this pull request as draft June 16, 2025 15:57

ilbertt added 3 commits June 17, 2025 09:34

fix: implement common traits for Type

ac6bb44

fix: traits impls

5d92e27

refactor: rename common type

cb0e67a

This was referenced Jun 27, 2025

feat: add support for doc comments #631

Closed

feat: support line comments as doc comments #635

Merged

ilbertt closed this in #635 Jul 2, 2025

ilbertt deleted the luca/support-comments branch July 10, 2025 08:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: support line comments #619

feat: support line comments #619

Uh oh!

ilbertt commented Jun 12, 2025

Uh oh!

github-actions bot commented Jun 13, 2025 •

edited

Loading

Uh oh!

christoph-dfinity commented Jun 17, 2025

Uh oh!

crusso commented Jun 17, 2025

Uh oh!

ilbertt commented Jun 17, 2025

Uh oh!

christoph-dfinity commented Jun 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: support line comments #619

feat: support line comments #619

Uh oh!

Conversation

ilbertt commented Jun 12, 2025

Uh oh!

github-actions bot commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

christoph-dfinity commented Jun 17, 2025

Uh oh!

crusso commented Jun 17, 2025

Uh oh!

ilbertt commented Jun 17, 2025

Uh oh!

christoph-dfinity commented Jun 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Jun 13, 2025 •

edited

Loading