search

kdl-org / kdl

the kdl document language specifications
https://kdl.dev
Other
1.09k stars 61 forks source link

Spec prose does not mention multi-line comments #262

Closed spaarmann closed 2 years ago

spaarmann commented 2 years ago

Apologies if I've just missed it, but while the spec prose mentions single-line comments in various places, multi-line comments do not appear at all except as part of the grammar at the end. For clarity's sake, and for people not familiar with the grammar syntax, should they be (briefly) mentioned in the prose too?

Based on the grammar, I think the intention is something like "multi-line comments may appear in any space that whitespace may appear", and perhaps "nested multi-line comments are supported"?

(Also, not sure if I'm missing something in the grammar that disallows this, but based on that first rule, I think something like

foo \ /* a multi-line comment being interpreted
         as "whitespace" in the `escline` definition
         and followed by a new-line */
     arg

is currently valid? Is that meant to be valid?)

zkat commented 2 years ago

Yeah that sounds about right. multi-line comments are treated as ws and you have: escline := '\\' ws* (single-line-comment | newline), meaning the \n after the */ gets treated as the one after the escaping \.

If you're so inclined, feel free to toss a PR our way to add prose for multiline comments to help clarify this? :)

spaarmann commented 2 years ago

Sure :) Did so in #263. Let me know if you want to tweak the wording or feel free to push edits yourself.