Directive syntax is not documented in language grammar

[nguerrera]

I noticed that we don't have the directive syntax documented in the grammar.

I further noticed that directives invalidate this comment since the trailing newline is significant to how a directive is parsed.

https://github.com/microsoft/cadl/blob/eb955d2fd79a3857760b1aba8a9bd6b9ea41c54c/packages/spec/src/spec.emu.html#L195-L200

[bterlson]

Interesting... I recall we discussed the #suppression syntax was supposed to mimic decorators and given the linebreak isn't necessary (AFAIK) maybe we just drop that part of it? So like #suppress "blah" "blah" model foo { } becomes valid-but-ugly?

[bterlson]

Ahh I take it back, I see you can have multiple suppression arguments. Yeah, this syntax is strange and I have regrets.

[timotheeguerin]

we could change it(require parentheses)

is that section not also invalid for single line comments?

[nguerrera]

Actually, you're right, we do need to specify what ends a single line comment. I'd be fine with saying newlines are CR, CRLF, or LF, period.

[timotheeguerin]

I do think though that not being able to run #suppress inline is an issue too

[nguerrera]

Hmm, we have LineTerminator referenced there, but not defined. Shouldn't grammarkdown have gotten mad?

[nguerrera]

If we're willing to take a breaking change, it should probably have been #directive(arg1, ..., argN). But that's a big break now, I think.

[timotheeguerin]

string literals also have some concept of new lines

[bterlson]

Ecmarkup is possibly using the ecmascript biblio, where the LineTerminator is defined. I think recent versions should not use it by default though.

I would also be fine just saying line breaks are what we currently support, but I know LS and PS are also common choices here.

[nguerrera]

I think LS and PS aren't worth supporting. Then you have to wonder "why not NEL?":

https://github.com/microsoft/TypeScript/blob/main/src/compiler/scanner.ts#L484-L485

Swift only supports CR, LF, and CRLF as well, and I don't think anyone will actually want to use anything else in practice in source code.

[nguerrera]

I think we can use this issue to update the grammar to reflect the current reality including fixing that incorrect comment about newline significance and having a definition of LineTerminatator that matches our current implementation.

And we can file separate issues if we want to change directive syntax or support additional newline characters. I'm inclined to say no to both: too breaking, and not worth it, so I will let someone else who might feel strongly about either of those file issues.

[nguerrera]

I don't think we need design here. We can update the spec to match the reality. If we want changes, then separate design issues can be filed.

[markcowl]

pri: 1
estimate: 3