Show comments for specific mappings in .vimrc

Question

I know that I can use :nmap, :vmap, :imap commands to display all the mapping for those 3 modes. However, I would like to display comments that I have for a single mapping.

So suppose I have the following entry in my vimrc:

" Execute current line in bash 
nmap <F9> :exec '!'.getline('.')<CR>

This could also look like this:

nmap <F9> :exec '!'.getline('.')<CR> " Execute current line in bash 

I would like to have a command that for this mapping that would look something like this:

<F9>      Execute current line in bash 

As this probably can only be done using custom function, where do I start? How do I parse .vimrc to strip only key mappings and their corresponding comments (I have only done some very basic Vim scripts)?

Do I understand correctly from :help map-comments that I should avoid inline comments in .vimrc?

Answer 1

It's very hard to "embed" comments into a mapping without affecting its functionality. And this would only help with our own mappings, not the ones from plugins.

Rather, I'd suggest to learn from (well-written) plugins, which provide :help targets for their (default) key mappings. So, to document your mapping(s), create a help file ~/.vim/doc/mymappings.txt with:

                                 *<F9>*
<F9>      Execute current line in bash

After :helptags ~/.vim/doc, you will be able to look up the comments via :h <F9>. By using the help file, you can use syntax highlighting, longer multi-line comments, and even examples, so I think that'a better and more straightforward solution.

Answer 2

Personally, I wouldn't have much use for such a feature for two reasons: the first one, is that I always have a vim session with a note taking buffer that contains all the tips/commands not yet in my muscle memory. Secondly, you can list all the maps using :map, and it's always a great exercise for your brain in learning vim to literally read vim commands.

That being said…

As this probably can only be done using custom function, where do I start?

…well I guess you could imagine using a function with a prototype such as:

AddMap(op, key, cmd, comment)

used like:

call AddMap("nmap", "<F9>", ":exec '!'.getline('.')<CR>", "Execute current line in shell")

which implementation would add key and comment to an array, so that you could list the array to get your own mappings declared. Using a function like ListMap().

let map_list = []

function! AddMap(op, key, cmd, comment)
  " add to map list
  insert(map_list, [op, key, comment])

  " execute map assign
  exec op.' '.key.' '.cmd
endfunction

function! ListMap()
  for it in map_list
    echo it[0] . '\t' . it[1] . '\t' . it[2]
  endfor
endfunction

Of course, one could elaborate on the ListMap() function implementation to generate a more "proper" help file that you could open in a buffer. But that's an idea of how you could do an implementation for a feature close to what you're looking for.

N.B.: this snippet is mostly an idea of how I'd tackle this problem, and it's a one shot write that I did not actually try.

How do I parse .vimrc to strip only key mappings and their corresponding comments (I have only done some very basic Vim scripts)?

I don't think that would be a good solution, I think the better way to achieve your goal is my suggestion. Simpler and more explicit, though it won't show off all mappings. But you don't have all your mappings in your .vimrc.

Do I understand correctly from :help map-comments that I should avoid inline comments in .vimrc?

To be more precise you shall not use inline comments after maps, because they will be interpreted part of the mapping.

how to get mapping created by plugins?

Besides, using :map, you just don't. You look at the sources/documenation of your plugins and find out about them. There's no such thing as a reverse lookup from runtime to declaration point.