Generalizing the custom block comment syntax `#>` about language-mcfunction HOT 6 CLOSED

Thanks, I appreciate your thoughts on this.

The reason it's difficult for me to decide is because I'm being pulled in two directions:

1. Make the default grammar more opinionated by mixing in concepts from IMP-Doc. I generally dislike this idea because I think the default grammar should not be influenced by what is effectively an arbitrary third-party format.
2. The opposite: make the default grammar less opinionated by removing the special block comment highlighting. Use a separate, extended opt-in grammar for this instead.

Perhaps the most reasonable thing to do here is to simply keep the default grammar as-is, and use the aforementioned separate, extended opt-in grammar for further additions to the block comments syntax.

Perhaps a "mcfunction-imp" grammar that goes all-out. People would be able to easily set this as their default grammar for mcfunction files with an editor like VSCode if they so desire. (I believe it's a single-line in user settings.json.)

from language-mcfunction.

I think the opt-in options makes the most sense. I feel it is best to represent the core language with accurate fidelity.

I feel there is also a large group of folks who would prefer to be led towards stronger optimization.

This is, of course, entirely based on the effort you'd like to put in.

from language-mcfunction.

I believe it is good to introduce new characters and have some nuance to what kind of comment is being left. I view this as something similar to markdown and the using hash symbols for H1, H2, H3, etc...

For me, I would take ~!@$ instead of just any character. I think its important to have some kind of limitation, so when we look at mcfunctions, they look and feel roughly the the same.

from language-mcfunction.

This will be addressed in version 0.18.0 of the extension.

For now, I've added a few extra characters to the block comment syntax:

I don't think this is the ideal solution, but I think it's better than keeping everyone locked into using # everywhere.

I'll probably consider removing the block comment highlighting (including the @annotation highlights) entirely from the default grammar again in the future, but not until extension grammars that provide detailed block comment highlighting are available. (For example, a mcfunction-imp grammar that injects itself into the mcfunction grammar's block comment scope.)

from language-mcfunction.

Sry for the late feedback, but I shortly wanna share my opinion:

I generally support the idea of block comments and doc comments.
But I think it is too early to include doc comments highlighting here. I think we should wait for more user feedback and until more users use it. To ask datapack tool developer about what they think they can and want to support is also something I consider a good step.

Like JSDoc was never in the language specification but is now included in the official highlighter. (To be fair, JSDoc had it a bit easier because of its inspiration from JavaDoc...)

I also find the idea of having a separated language grammar for the doc comments that can register as a module in this one a good one. Maybe we can also expand on this idea in different directions.

from language-mcfunction.

@ShadowCreator250 This issue and the changes recently pushed in version 0.18.0 don't include any doc comment highlighting apart from what was already present. The only change was expanding the pool of possible characters that activate the existing block comment highlighting. Any further support for doc comment highlighting is not planned for language-mcfunction.

IMP-Doc is a separate project that attempts to define a proper doc comment format. At some point IMP-Doc might ship its own grammar extension that injects itself into the grammar provided by language-mcfunction. I don't want to force this into the default grammar because the vast majority of users aren't concerned with doc comments and because it would stunt the growth of IMP-Doc. See Arcensoth/imp-spec#1 (comment) for more context.

from language-mcfunction.