From 73de98256cf3932dca156fbfd0c82c1cc10d487e Mon Sep 17 00:00:00 2001
From: Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Date: Thu, 4 Apr 2024 18:10:12 +0300
Subject: feat(comment): add built-in commenting

Design

- Enable commenting support only through `gc` mappings for simplicity.
  No ability to configure, no Lua module, no user commands. Yet.

- Overall implementation is a simplified version of 'mini.comment'
  module of 'echasnovski/mini.nvim' adapted to be a better suit for
  core. It basically means reducing code paths which use only specific
  fixed set of plugin config.

  All used options are default except `pad_comment_parts = false`. This
  means that 'commentstring' option is used as is without forcing single
  space inner padding.

As 'tpope/vim-commentary' was considered for inclusion earlier, here is
a quick summary of how this commit differs from it:

- **User-facing features**. Both implement similar user-facing mappings.
  This commit does not include `gcu` which is essentially a `gcgc`.
  There are no commands, events, or configuration in this commit.

- **Size**. Both have reasonably comparable number of lines of code,
  while this commit has more comments in tricky areas.

- **Maintainability**. This commit has (purely subjectively) better
  readability, tests, and Lua types.

- **Configurability**. This commit has no user configuration, while
  'vim-commentary' has some (partially as a counter-measure to possibly
  modifying 'commentstring' option).

- **Extra features**:
    - This commit supports tree-sitter by computing `'commentstring'`
      option under cursor, which can matter in presence of tree-sitter
      injected languages.

    - This commit comments blank lines while 'tpope/vim-commentary' does
      not. At the same time, blank lines are not taken into account when
      deciding the toggle action.

    - This commit has much better speed on larger chunks of lines (like
      above 1000). This is thanks to using `nvim_buf_set_lines()` to set
      all new lines at once, and not with `vim.fn.setline()`.
---
 runtime/doc/news.txt     |  2 ++
 runtime/doc/various.txt  | 38 ++++++++++++++++++++++++++++++++++++++
 runtime/doc/vim_diff.txt |  2 ++
 3 files changed, 42 insertions(+)

(limited to 'runtime/doc')

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 5aa274637b..c219762c3f 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -346,6 +346,8 @@ The following new APIs and features were added.
 
 • |extmarks| option `scoped`: only show the extmarks in its namespace's scope.
 
+• Added built-in |commenting| support.
+
 ==============================================================================
 CHANGED FEATURES                                                 *news-changed*
 
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 33f57580c7..803ca95cdf 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -557,5 +557,43 @@ LessInitFunc in your vimrc, for example: >
 	  set nocursorcolumn nocursorline
 	endfunc
 <
+==============================================================================
+3. Commenting							*commenting*
+
+Nvim supports commenting and uncommenting of lines based on 'commentstring'.
+
+Acting on a single line behaves as follows:
+- If the line matches 'commentstring', the comment markers are removed (e.g.
+  `/*foo*/` is transformed to `foo`).
+- Otherwise the comment markers are added to the current line (e.g. `foo` is
+  transformed to `/*foo*/`). Blank lines are ignored.
+
+Acting on multiple lines behaves as follows:
+- If each affected non-blank line matches 'commentstring', then all comment
+  markers are removed.
+- Otherwise all affected lines are converted to comments; blank lines are
+  transformed to empty comments (e.g. `/**/`). Comment markers are aligned to
+  the least indented line.
+
+If the filetype of the buffer is associated with a language for which a
+|treesitter| parser is installed, then |vim.filetype.get_option()| is called
+to look up the value of 'commentstring' corresponding to the cursor position.
+(This can be different from the buffer's 'commentstring' in case of
+|treesitter-language-injections|.)
+
+							*gc-default*
+gc{motion}		Comment or uncomment lines covered by {motion}.
+
+							*gcc-default*
+gcc			Comment or uncomment [count] lines starting at cursor.
+
+							*v_gc-default*
+{Visual}gc		Comment or uncomment the selected line(s).
+
+							*o_gc-default*
+gc			Text object for the largest contiguous block of
+			non-blank commented lines around the cursor (e.g.
+			`gcgc` uncomments a comment block; `dgc` deletes it).
+			Works only in Operator-pending mode.
 
  vim:noet:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index a76166abf7..82f3fe9b1b 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -134,6 +134,8 @@ of these in your config by simply removing the mapping, e.g. ":unmap Y".
 - @ |v_@-default|
 - # |v_#-default|
 - * |v_star-default|
+- gc |gc-default| |v_gc-default| |o_gc-default|
+- gcc |gcc-default|
 - Nvim LSP client defaults |lsp-defaults|
   - K |K-lsp-default|
 
-- 
cgit