End-of-line comments in key mappings treated like options

[gwuen]

When including a comment on the same line as a custom key mapping, it is treated like an option. Since v2.2.0, you can observe this in the help dialog, where the options of a command are now displayed in parentheses. For example, using the key map definition map ' Marks.activateGotoMode " alias for backtick:

According to this comment on #3839, this is supposed to be a feature, not a bug:

a "#" which is not at the start of a line doesn't mean a comment, but will be treated as an option of the mapping.

I think this is unintuitive, as the key map syntax closely resembles Vim's, where end-of-line comments are treated as such. At the very least, this is badly documented behavior: The example shown next to the key mappings input field does not make it clear a new line is necessary. Only when the end-of-line comment is included on an unmap line, you get a warning, since its syntax doesn't allow any options.

While I would like to see working end-of-line comments, I can understand if this will not be changed for simplicity's sake, but it would be great to see this behavior clearly documented somewhere.

[philc]

I'll look into this as part of the ongoing work on the options page.

[philc]

I implemented this in a local branch and found a few complexities:

1. We want to support the #, ' and " characters when they're present in these commands, because they represent valid keys which can be mapped:
   • map # createTab
   • unmap # createTab
   • mapkey # a
2. Commands which accept URLs (createTab) or arbitrary strings (Vomnibar.activate with the query option) require special consideration. They options contain these characters, although it's probably very uncommon to have a string with an unescaped space preceding the comment character.

In my implementation, I hard-coded exceptions for No 1. No 2 isn't fully fixable without requiring that arbitrary string options be encoded with quotes or something. #4591 has a related discussion about how to encode spaces.

Another approach is to require all comment characters be escaped when used in commands or options if you want them to be ignored, although that will very likely break existing configs.

Supporting this has enough of a bad smell that I'm inclined to say we don't allow trailing comments on lines, and add that documentation next to the "Custom key mappings" textbox in the options page.

[philg-dev]

Supporting this has enough of a bad smell that I'm inclined to say we don't allow trailing comments on lines, and add that documentation next to the "Custom key mappings" textbox in the options page.

That sounds like a reasonable way to go IMHO. @philc While you're editing the documentation in the options page, maybe a reference to the Readme section would be a good idea too, since there's a list of special characters and their syntax. This came up in #4686 recently.