mini-comment.txt

*mini.comment* Comment lines
*MiniComment*

MIT License Copyright (c) 2021 Evgeni Chasnovski

==============================================================================

Features:
- Commenting in Normal mode respects |count| and is dot-repeatable.

- Comment structure is inferred from 'commentstring': either from current
  buffer or from locally active tree-sitter language (only on Neovim>=0.9).

- Allows custom hooks before and after successful commenting.

- Configurable options for some nuanced behavior.

What it doesn't do:
- Block and sub-line comments. This will only support per-line commenting.

- Configurable (from module) comment structure. Modify |commentstring| instead.

- Handle indentation with mixed tab and space.

- Preserve trailing whitespace in empty lines.

Notes:
- To use tree-sitter aware commenting, global value of 'commentstring'
  should be `''` (empty string). This is the default value in Neovim>=0.9,
  so make sure to not set it manually.

# Setup~

This module needs a setup with `require('mini.comment').setup({})` (replace
`{}` with your `config` table). It will create global Lua table
`MiniComment` which you can use for scripting or manually (with
`:lua MiniComment.*`).

See |MiniComment.config| for `config` structure and default values.

You can override runtime config settings locally to buffer inside
`vim.b.minicomment_config` which should have same structure as
`MiniComment.config`. See |mini.nvim-buffer-local-config| for more details.

# Disabling~

To disable core functionality, set `vim.g.minicomment_disable` (globally) or
`vim.b.minicomment_disable` (for a buffer) to `true`. Considering high number
of different scenarios and customization intentions, writing exact rules
for disabling module's functionality is left to user. See
|mini.nvim-disabling-recipes| for common recipes.

------------------------------------------------------------------------------
                                                           *MiniComment.setup()*
                         `MiniComment.setup`({config})
Module setup

Parameters~
{config} `(table|nil)` Module config table. See |MiniComment.config|.

Usage~
`require('mini.comment').setup({})` (replace `{}` with your `config` table)

------------------------------------------------------------------------------
                                                            *MiniComment.config*
                              `MiniComment.config`
Module config

Default values:
>
  MiniComment.config = {
    -- Options which control module behavior
    options = {
      -- Whether to ignore blank lines
      ignore_blank_line = false,

      -- Whether to recognize as comment only lines without indent
      start_of_line = false,

      -- Whether to ensure single space pad for comment parts
      pad_comment_parts = true,
    },

    -- Module mappings. Use `''` (empty string) to disable one.
    mappings = {
      -- Toggle comment (like `gcip` - comment inner paragraph) for both
      -- Normal and Visual modes
      comment = 'gc',

      -- Toggle comment on current line
      comment_line = 'gcc',

      -- Define 'comment' textobject (like `dgc` - delete whole comment block)
      textobject = 'gc',
    },

    -- Hook functions to be executed at certain stage of commenting
    hooks = {
      -- Before successful commenting. Does nothing by default.
      pre = function() end,
      -- After successful commenting. Does nothing by default.
      post = function() end,
    },
  }
<

------------------------------------------------------------------------------
                                                        *MiniComment.operator()*
                         `MiniComment.operator`({mode})
Main function to be mapped

It is meant to be used in expression mappings (see |map-<expr>|) to enable
dot-repeatability and commenting on range. There is no need to do this
manually, everything is done inside |MiniComment.setup()|.

It has a somewhat unintuitive logic (because of how expression mapping with
dot-repeatability works): it should be called without arguments inside
expression mapping and with argument when action should be performed.

Parameters~
{mode} `(string|nil)` Optional string with 'operatorfunc' mode (see |g@|).

Return~
`(string|nil)` 'g@' if called without argument, '' otherwise (but after
  performing action).

------------------------------------------------------------------------------
                                                    *MiniComment.toggle_lines()*
          `MiniComment.toggle_lines`({line_start}, {line_end}, {opts})
Toggle comments between two line numbers

It uncomments if lines are comment (every line is a comment) and comments
otherwise. It respects indentation and doesn't insert trailing
whitespace. Toggle commenting not in visual mode is also dot-repeatable
and respects |count|.

Before successful commenting it executes `config.hooks.pre`.
After successful commenting it executes `config.hooks.post`.
If hook returns `false`, any further action is terminated.

# Notes ~

- Comment structure is inferred from buffer's 'commentstring' option or
  local language of tree-sitter parser (if active; only on Neovim>=0.9).

- Currently call to this function will remove marks inside written range.
  Use |lockmarks| to preserve marks.

Parameters~
{line_start} `(number)` Start line number (inclusive from 1 to number of lines).
{line_end} `(number)` End line number (inclusive from 1 to number of lines).
{opts} `(table|nil)` Options. Possible fields:
  - <ref_position> `(table)` - A two-value array with `{ row, col }` (both
    starting at 1) of reference position at which local tree-sitter value of
    'commentstring' will be computed (if tree-sitter is active).
    Default: `{ line_start, 1 }`.

------------------------------------------------------------------------------
                                                      *MiniComment.textobject()*
                           `MiniComment.textobject`()
Select comment textobject

This selects all commented lines adjacent to cursor line (if it itself is
commented). Designed to be used with operator mode mappings (see |mapmode-o|).

Before successful selection it executes `config.hooks.pre`.
After successful selection it executes `config.hooks.post`.
If hook returns `false`, any further action is terminated.


 vim:tw=78:ts=8:noet:ft=help:norl: