Support plain --[[ ]] block comments

[vocksel]

A problem I have when writing moonwave docs is that typing out --[=[ ]=] is very tedious because it requires 7 keystrokes to write out: (The pipe | represents the cursor position)

1. -|
2. --|
3. --[|]
4. --[=|]
5. --[=[|]]
6. --[=[]|]
7. --[=[]=|]

Whereas with regular block comments it only takes 4 keystrokes, which is also easier to type out quickly since there is no alternating between brackets and equal signs.

1. -|
2. --|
3. --[|]
4. --[[|]]

Another issue I am having with --[=[ ]=] comments is that Rewrap does not recognize them as valid comments, so I have to manually set the line breaks for my documentation instead of having it handled via a keybind.

It would be great if moonwave could parse plain doc comments. I realize that using --[=[ ]=] is because they are uncommon, so moonwave can make the assumption that any comment written like this should be managed by it. I think a fair compromise could be to include a @moonwave tag or similar so that doc comments that shouldn't be managed by moonwave are not automatically picked up.

[evaera]

For VSCode, you can create a snippet in your user snippets folder to create a doc comment:

	"Doc Comment": {
		"prefix": "doc",
		"body": [
			"--[=[",
			"\t$1",
			"]=]"
		]
	},

Then, when you write doc and auto complete, it will fill out the doc comment branches.

I don't think parsing plain block comments is something we want to do. There are many plain doc comments out there in the wild, and I want it to be clear in the ecosystem that --[=[ means a doc comment. Previously, things like LuaDoc used the triple-dash notation (---) so that was already associated with doc comments. I want to be careful about adding too many options here because I think it might make it harder to immediately know what it means.

From an implementation perspective, this is also difficult to do, because we perform some validation and parsing before we even start looking at what tags the user has used. We would have to refactor some code to support this. The proposed solution is also incongruous with the existing doc comments (needing a @moonwave tag), and I think it might confuse users who don't know what it means.

Overall, I just want to keep things simple. I think most of the issues you brought up are actually issues with Lua tooling being bad (no surprise to any of us there) rather than a problem with Moonwave itself.

[evaera]

It seems like there is already an open issue for Rewrap about this issue: stkb/Rewrap#290

[vocksel]

I agree, this is better fixed at the tooling level, not as a part of Moonwave. Thanks for the detailed explanation