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>

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
+							*gC*
-supports it (that is, whenever the comment marker precedes the code) and fall
+gC              to comment/uncomment to end of current line (same as `gc$`)
-back to `gcc` otherwise, add the following mapping to your vimrc: >
+
+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:

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*

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()
+nnoremap <silent> <expr> <Plug>(comment-toggle) comment.Toggle()
-xnoremap <silent> <expr> gc comment.Toggle()
+xnoremap <silent> <expr> <Plug>(comment-toggle) comment.Toggle()
-nnoremap <silent> <expr> gcc 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> <Plug>(comment-text-object-inner) <scriptcmd>comment.ObjComment(v:true)<CR>
-onoremap <silent>ac <scriptcmd>comment.ObjComment(v:false)<CR>
+onoremap <silent> <Plug>(comment-text-object-outer) <scriptcmd>comment.ObjComment(v:false)<CR>
-xnoremap <silent>ic <esc><scriptcmd>comment.ObjComment(v:true)<CR>
+xnoremap <silent> <Plug>(comment-text-object-inner) <esc><scriptcmd>comment.ObjComment(v:true)<CR>
-xnoremap <silent>ac <esc><scriptcmd>comment.ObjComment(v:false)<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