Proposal: Multi-line comments

[Bryan-Legend]

/* Yarnspinner is often used for intensive writing tasks, so it should support multi-line comments for writing outlines and other story documentation.

Also, they can be handy to comment out entire nodes. */

[McJones]

I am going to close this issue as something we don't intend on adding to the language, but I'd like to give you our reasoning as this is something that we've discussed a fair bit before internally way back in the pre v1 release days of Yarn Spinner.

So the first and major issue is adding multi-line comments actually adds a surprisingly large amount of complexity to the parsing of yarn (or any language tbh). In that correctly handling all the nesting of comments and mixing elements that aren't comments but look the same is particularly brutal to the parser grammar. As an example of this:

/*
Calculator: hello, I am a calculator
Player: What can you do?
Calculator: I can perform the following +-*/
*/

Sure this example is one I made up on the spot but how should this be handled? And this is true with also just nesting the multi-line comments in general. So take the following example:

/*
Here is some regular text
/*
Here is some more text inside a nested comment
*/
Here is some text outside the nested comment
*/

In this current form should the parser have seen two comment blocks or one? And where should the top level comment end? If we delete the top comment opening terminal is there now an error?

So the options are to:

• not allow multi-line comments
• not allow multi-line comment elements nested inside multi-line comments
• force users to escape multi-line comment elements
• implement nested comment ranges and handle every edge case that presents

Secondly in our recommended editor of VSCode if you select a block of text and press Ctrl (or Command on macOS) and / it will automatically append the // comment terminal to the front of the line. Pressing Ctrl + / again will remove the //, giving an easy way to comment and uncomment lines in bulk.

Overall we decided that the quick line comment feature of VSCode gives enough of the benefits of multi-line comments, without any of the edge cases, so we haven't implemented them. I hope this clears up why we don't see any real benefit to multi-line comments.