Improve readability of annotation syntaxes

[carsakiller]

The method currently used for describing how to use annotations can be easy to understand at times:
---@type <type>

And also impossible for mere mortals to understand:
---@cast <value_name> [+|-]<type|?>[, [+|-]<type|?>...]
---@overload fun([param: type[, param: type...]]): [return_value[,return_value]]

There must be a better way to represent these more complex syntaxes while also not using symbols regularly in use (<, >, (, ), [, ], {, }, @, #, -, +, =, :, ", ,, ., ?). Although now that I have listed some in-use symbols, I realize we really are quite limited. It is hard to explain a syntax that uses many symbols… using symbols.

I'm open to any suggestions on how this can be improved 🙂

[CelDaemon]

Maybe using colors to differentiate between placeholders and real syntax?
It doesn't have to just be colors, a hover card describing possible example values could also help.

[carsakiller]

My initial thought was to use colours, but there could be issues then with colourblind users. I think I'll give it a try using iWantHue and see how it looks.

[carsakiller]

I'm not really sure whether this is better 😆

It might just be slightly easier to read than the current definition:

I can try adding a colour specifically for the repeatable brackets… maybe that will help in the case of @cast.

[tomlau10]

Maybe define the [+|-]<type|?> part as a variable first?

<type_def> := [+|-]<type|?>
---@cast <value_name> <type_def>[, <type_def>...]