Allow \ to escape newline in multi-line strings

[mikekistler]

Currently TypeSpec adds a newline (\n) at the end of every line except the last of a multi-line string. This is consistent with the behavior of many HLLs like JavaScript and Python. But those languages also allow a backslash () to escape that newline. TypeSpec should have a similar feature.

JavaScript

> foo = "bar \
... baz"
'bar baz'
> 

Python

>>> foo = """bar \
... baz"""
>>> foo
'bar baz'
>>> 

[bterlson]

I think this would be quite welcome for multi-line strings, and I think aligns with our string-inspo language Swift:

@doc("""
this is \
all one \
line.
""")

[mikekistler]

@markcowl I'd like to lobby to raise the priority on this issue. The current state of things is that developers must choose between using multi-line strings in doc comments for code readability, at the expense of extraneous newlines inserted into generated docs, and forgoing multi-line strings and code readability to get good docs.

To illustrate, this multi-line doc comment in AnomalyDetector:

@summary("Detect Multivariate Anomaly")
@doc("""
Submit a multivariate anomaly detection task with the modelId value of a trained model
and inference data. The input schema should be the same with the training
request. The request will finish asynchronously and return a resultId value to
query the detection result. The request should be a source link to indicate an
externally accessible Azure Storage URI that either points to an Azure Blob
Storage folder or points to a CSV file in Azure Blob Storage.
""")
op DetectMultivariateBatchAnomaly(

Results in this formatted documentation:

[nguerrera]

+1 from me. It does match Swift and thankfully, this is a non-breaking change since it would be an "invalid escape sequence" error today.

[nguerrera]

We should think about how to specify the same no-line-break in a /** */ comment. Unfortunately, Using \ at end-of-line there is valid and puts a literal \ in the @doc value.

I also find myself kind of wishing I didn't need the backslashes and something processed this as markdown to decide where the hard breaks really should go.

This is all separate and can be tracked with distinct issues. Adding escaped line break to multi-line strings is still goodness on its own.

[timotheeguerin]

it is a bit breaking but if we assumed that doc comment are markdown shouldn't it remove the new lines unless you ahve 2

(Rendering markdown)

[timotheeguerin]

hhm but by that same logic so does @doc which we also said was markdown I think

[bterlson]

My feeling is that @doc should be considered plaintext from the perspective of core, i.e. we should preserve any line breaks in the input string. That said, for our usage, I believe we should treat them markdown or html, and as such I would expect line breaks to not show up in the output unless we did a step replacing \n with <br>. Fixing this issue feels like the key to me, it would be sad if \ were needed at the end of the line for every doc comment (but we should support it anyway as sometimes its needed).

[mikekistler]

Followed up with Brian today and it seems that the docs example above is a case of bad docs rendering. MS Learn formats this content properly, flowing it as appropriate for Markdown content.

On that basis, I retract my request to raise the priority on this issue. It's a "nice to have" but not required to get well-formatted docs.