1cbe3e89c9
vim9script <expr> mappings relying on imports cannot be evaluated outside of the script file with the imports, so do not work with plugins like vim-which-key, which evaluates <expr> mappings to apply them. Using <Plug> mappings is one way to address this, and has the added benefit of reading like a description for users finding the mappings. fixes: #17523 closes: #17563 Signed-off-by: Mark Woods <mwoods.online.ie@gmail.com> Signed-off-by: Christian Brabandt <cb@256bit.org>
132 lines
4.7 KiB
Plaintext
132 lines
4.7 KiB
Plaintext
*comment.txt* For Vim version 9.1. Last change: 2025 Jun 22
|
|
|
|
|
|
VIM REFERENCE MANUAL
|
|
|
|
Commenting and un-commenting text.
|
|
|
|
==============================================================================
|
|
|
|
See |comment-install| on how to activate this package.
|
|
|
|
The comment.vim package, allows to toggle comments for a single line, a range
|
|
of lines or a selected text object. It defines the following mappings:
|
|
|
|
*o_gc*
|
|
gc{motion} to toggle comments for the selected motion
|
|
*v_gc*
|
|
{Visual}gc to comment/uncomment the highlighted lines.
|
|
|
|
Since gc operates on a motion, it can be used with any motion, for example _
|
|
to comment the current line, or ip to comment the current paragraph.
|
|
Default mappings are defined for `gc_` and `gc$`:
|
|
*gcc*
|
|
gcc to comment/uncomment current line (same as `gc_`)
|
|
|
|
*gC*
|
|
gC to comment/uncomment to end of current line (same as `gc$`)
|
|
|
|
Commenting to the end of a line using `gC` works whenever the filetype plugin
|
|
supports it (that is, whenever the comment marker precedes the code) and falls
|
|
back to `gcc` otherwise.
|
|
|
|
Note: using `gC` may not always result in valid comment markers depending on
|
|
the language used.
|
|
|
|
Additionally, the plugin defines a comment text-object which requires syntax
|
|
highlighting to be enabled.
|
|
*v_ac* *ac*
|
|
ac "a comment", select current or next comment.
|
|
Leading and trailing white space is included.
|
|
Trailing newlines are included too.
|
|
*v_ic* *ic*
|
|
ic "inner comment", select current or next comment.
|
|
|
|
This plugin uses the buffer-local 'commentstring' option value to add or remove
|
|
comment markers to the selected lines. Whether it will comment or un-comment
|
|
depends on the range of lines to act upon. When all of the lines in range
|
|
have comment markers, all lines will be un-commented, if it doesn't, the lines
|
|
will be commented out. Blank and empty lines are ignored.
|
|
|
|
The value of 'commentstring' is the same for the entire buffer and determined
|
|
by its filetype (|filetypes|). To adapt it within the buffer for embedded
|
|
languages, you can use a plug-in such as
|
|
https://github.com/suy/vim-context-commentstring.
|
|
|
|
The comment marker will always be padded with blanks whether or not the
|
|
'commentstring' value contains whitespace around "%s".
|
|
|
|
If the mapping does not seem to work (or uses wrong comment markers), it might
|
|
be because of several reasons:
|
|
- the filetype is not detected by Vim, see |new-filetype|,
|
|
- filetype plugins are not enabled, see |:filetype-plugin-on| or
|
|
- the filetype plugin does not set the (correct) 'commentstring' option.
|
|
|
|
You can simply configure this using the following autocommand (e.g. for legacy
|
|
Vim script): >
|
|
|
|
autocmd Filetype vim :setlocal commentstring="%s
|
|
|
|
This example sets the " as start of a comment for legacy Vim script. For Vim9
|
|
script, you would instead use the "#" char: >
|
|
|
|
autocmd Filetype vim :setlocal commentstring=#\ %s
|
|
|
|
==============================================================================
|
|
Options:
|
|
|
|
*g:comment_first_col*
|
|
*b:comment_first_col*
|
|
By default comment chars are added in front of the line, i.e. if the line
|
|
was indented, commented line would stay indented as well.
|
|
|
|
However some filetypes require a comment char on the first column, use this option
|
|
to change default behaviour.
|
|
|
|
Use g:comment_first_col to change it globally or b:comment_first_col to
|
|
target specific filetype(s).
|
|
|
|
*g:comment_mappings*
|
|
Set to false to disable the default keyboard mappings, e.g. in your vimrc
|
|
>
|
|
let g:comment_mappings = v:false
|
|
<
|
|
This option must be set before the package is activated using |packadd|.
|
|
|
|
==============================================================================
|
|
Mappings:
|
|
|
|
The following |<Plug>| mappings are included, which you can use to customise the
|
|
keyboard mappings.
|
|
|
|
*<Plug>(comment-toggle)*
|
|
Normal and visual modes, mapped to gc by default
|
|
|
|
*<Plug>(comment-toggle-line)*
|
|
Normal mode only, mapped to gcc by default
|
|
|
|
*<Plug>(comment-toggle-end)*
|
|
Normal mode only, mapped to gC by default
|
|
|
|
*<Plug>(comment-text-object-inner)*
|
|
Operator pending and visual modes, mapped to ic by default
|
|
|
|
*<Plug>(comment-text-object-outer)*
|
|
Operator pending and visual modes, mapped to ac by default
|
|
|
|
The default keyboard mappings are shown below, you can copy these if you wish
|
|
to customise them in your vimrc:
|
|
>
|
|
nmap gc <Plug>(comment-toggle)
|
|
xmap gc <Plug>(comment-toggle)
|
|
nmap gcc <Plug>(comment-toggle-line)
|
|
nmap gC <Plug>(comment-toggle-end)
|
|
|
|
omap ic <Plug>(comment-text-object-inner)
|
|
omap ac <Plug>(comment-text-object-outer)
|
|
xmap ic <Plug>(comment-text-object-inner)
|
|
xmap ac <Plug>(comment-text-object-outer)
|
|
<
|
|
==============================================================================
|
|
vim:tw=78:ts=8:fo=tcq2:ft=help:
|