Generalizing the custom block comment syntax #>

[Arcensoth]

The custom block comment syntax introduced by language-mcfunction was inspired by my own usage; the same usage that eventually lead to the documentation format IMP-Doc.

Those involved with IMP-Doc have discussed additional comment prefixes (specifically for IMP-Doc) to denote different types of directives, because the existing block comment syntax #> is limited but has resulted in a variety of use-cases.

Now, as far as I'm concerned, IMP-Doc is its own independent project and has no influence over language-mcfunction's default (GitHub) grammar. However, the issue raised by IMP-Doc begs the question: could language-mcfunction benefit from a similar change?

I think it's important to keep the base language-mcfunction grammar separate from and uninfluenced by IMP-Doc, because the way GitHub highlights comments should not be influenced by (what is effectively) an arbitrary third-party documentation format.

However, it could be argued that language-mcfunction's block comment syntax #> was based on an equally arbitrary decision. Perhaps it should have never been added and should be removed in a future update, to eliminate any possible confusion. This is a fair argument.

That being said, I think it's also fair to argue that block comment syntax #> should be kept simply because of how useful it's proven itself in practice. Moreover; perhaps it's also fair to argue that this syntax should be generalized, to reduce the impact of the initial (arbitrary) decision to choose > as the trigger character.

---

In short: I'd like to generalize the custom block comment syntax #> by extending the set of trigger characters. This would widen the pool of possible options for users as well as third-party formats/tools. For example: instead of just using > to initiate a block comment, make it so that any special character out of, say, ~!@$%^*, or even \W (any non-word character), does the same thing.

Any thoughts/comments/concerns are appreciated.

[Moesh]

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.

[Arcensoth]

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.)

[Moesh]

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.

[Arcensoth]

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.)

[ShadowCreator250]

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.

[Arcensoth]

@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.