feat: support line comments

[ilbertt]

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]

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]

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]

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

[ilbertt]

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

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)