runtime(comment): add <Plug>-mappings
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>
diff --git a/runtime/pack/dist/opt/comment/doc/comment.txt b/runtime/pack/dist/opt/comment/doc/comment.txt
index be8cb84..2286f07 100644
--- a/runtime/pack/dist/opt/comment/doc/comment.txt
+++ b/runtime/pack/dist/opt/comment/doc/comment.txt
@@ -1,4 +1,4 @@
-*comment.txt* For Vim version 9.1. Last change: 2025 Mar 21
+*comment.txt* For Vim version 9.1. Last change: 2025 Jun 22
VIM REFERENCE MANUAL
@@ -19,16 +19,17 @@
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.
-A default mapping `gcc` to `gc_` is defined:
+Default mappings are defined for `gc_` and `gc$`:
*gcc*
-gcc to comment/uncomment current line
+gcc to comment/uncomment current line (same as `gc_`)
-To comment the rest of the line by `gC` whenever the filetype plugin
-supports it (that is, whenever the comment marker precedes the code) and fall
-back to `gcc` otherwise, add the following mapping to your vimrc: >
+ *gC*
+gC to comment/uncomment to end of current line (same as `gc$`)
- nnoremap <silent> <expr> gC comment#Toggle() .. '$'
-<
+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.
@@ -85,5 +86,46 @@
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:
diff --git a/runtime/pack/dist/opt/comment/doc/tags b/runtime/pack/dist/opt/comment/doc/tags
index 62c4afd..6096d11 100644
--- a/runtime/pack/dist/opt/comment/doc/tags
+++ b/runtime/pack/dist/opt/comment/doc/tags
@@ -1,7 +1,14 @@
+<Plug>(comment-text-object-inner) comment.txt /*<Plug>(comment-text-object-inner)*
+<Plug>(comment-text-object-outer) comment.txt /*<Plug>(comment-text-object-outer)*
+<Plug>(comment-toggle) comment.txt /*<Plug>(comment-toggle)*
+<Plug>(comment-toggle-end) comment.txt /*<Plug>(comment-toggle-end)*
+<Plug>(comment-toggle-line) comment.txt /*<Plug>(comment-toggle-line)*
ac comment.txt /*ac*
b:comment_first_col comment.txt /*b:comment_first_col*
comment.txt comment.txt /*comment.txt*
g:comment_first_col comment.txt /*g:comment_first_col*
+g:comment_mappings comment.txt /*g:comment_mappings*
+gC comment.txt /*gC*
gcc comment.txt /*gcc*
ic comment.txt /*ic*
o_gc comment.txt /*o_gc*
diff --git a/runtime/pack/dist/opt/comment/plugin/comment.vim b/runtime/pack/dist/opt/comment/plugin/comment.vim
index 67b431d..62817dd 100644
--- a/runtime/pack/dist/opt/comment/plugin/comment.vim
+++ b/runtime/pack/dist/opt/comment/plugin/comment.vim
@@ -2,14 +2,28 @@
# Maintainer: Maxim Kim <habamax@gmail.com>
# Last Update: 2025 Mar 21
+# 2025 Jun 22 by Vim Project: add <Plug> mappings #17563
import autoload 'comment.vim'
-nnoremap <silent> <expr> gc comment.Toggle()
-xnoremap <silent> <expr> gc comment.Toggle()
-nnoremap <silent> <expr> gcc comment.Toggle() .. '_'
+nnoremap <silent> <expr> <Plug>(comment-toggle) comment.Toggle()
+xnoremap <silent> <expr> <Plug>(comment-toggle) comment.Toggle()
+nnoremap <silent> <expr> <Plug>(comment-toggle-line) comment.Toggle() .. '_'
+nnoremap <silent> <expr> <Plug>(comment-toggle-end) comment.Toggle() .. '$'
-onoremap <silent>ic <scriptcmd>comment.ObjComment(v:true)<CR>
-onoremap <silent>ac <scriptcmd>comment.ObjComment(v:false)<CR>
-xnoremap <silent>ic <esc><scriptcmd>comment.ObjComment(v:true)<CR>
-xnoremap <silent>ac <esc><scriptcmd>comment.ObjComment(v:false)<CR>
+onoremap <silent> <Plug>(comment-text-object-inner) <scriptcmd>comment.ObjComment(v:true)<CR>
+onoremap <silent> <Plug>(comment-text-object-outer) <scriptcmd>comment.ObjComment(v:false)<CR>
+xnoremap <silent> <Plug>(comment-text-object-inner) <esc><scriptcmd>comment.ObjComment(v:true)<CR>
+xnoremap <silent> <Plug>(comment-text-object-outer) <esc><scriptcmd>comment.ObjComment(v:false)<CR>
+
+if get(g:, 'comment_mappings', true)
+ 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)
+endif