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 be8cb84e65adcf8a42647eda3f3ef4e312093fef..2286f07851ab82d43b5f0f74afeb3a237a7a44c3 100644 (file)
--- 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 @@ gc{motion}  to toggle comments for the selected motion
 
 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$`)
+
+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.
 
-       nnoremap <silent> <expr> gC comment#Toggle() .. '$'
-<
 Note: using `gC` may not always result in valid comment markers depending on
 the language used.
 
@@ -85,5 +86,46 @@ Options:
     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 62c4afd6d9683ad6ec3755f52a4b3dc14cb1ca5d..6096d114ca9a962a16bd3d9c782bb1314fbec05f 100644 (file)
--- 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 67b431de6ee3a466b27890f53d08e24aafee117f..62817ddfe0e6d394277f28af718b65d16e89e181 100644 (file)
--- a/runtime/pack/dist/opt/comment/plugin/comment.vim
+++ b/runtime/pack/dist/opt/comment/plugin/comment.vim
@@ -2,14 +2,28 @@ vim9script
 
 # 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