more stuff

Author: numToStr

.github/workflows/ci.yaml

@@ -6,7 +6,6 @@ on:
       - "**.lua"
     branches:
       - master
-      - docs
 
 env:
   PLUGIN_NAME: Comment

.gitignore

@@ -41,3 +41,6 @@ luac.out
 
 tmp
 scratch
+
+# ignore generated doc tags
+doc/tags

README.md

@@ -37,6 +37,10 @@ Plug 'numToStr/Comment.nvim'
 lua require('Comment').setup()
 ```
 
+### 📖 Getting Help
+
+`Comment.nvim` provides help docs which can be accessed by running `:help comment-nvim`
+
 <a id="setup"></a>
 
 ### ⚒️ Setup
@@ -68,41 +72,26 @@ Following are the **default** config for the [`setup()`](#setup). If you want to
 ```lua
 {
     ---Add a space b/w comment and the line
-    ---@type boolean|fun():boolean
     padding = true,
-
     ---Whether the cursor should stay at its position
-    ---NOTE: This only affects NORMAL mode mappings and doesn't work with dot-repeat
-    ---@type boolean
     sticky = true,
-
-    ---Lines to be ignored while comment/uncomment.
-    ---Could be a regex string or a function that returns a regex string.
-    ---Example: Use '^$' to ignore empty lines
-    ---@type string|fun():string
+    ---Lines to be ignored while (un)comment
     ignore = nil,
-
     ---LHS of toggle mappings in NORMAL mode
-    ---@type table
     toggler = {
         ---Line-comment toggle keymap
         line = 'gcc',
         ---Block-comment toggle keymap
         block = 'gbc',
     },
-
-    ---LHS of operator-pending mappings in NORMAL mode
-    ---LHS of mapping in VISUAL mode
-    ---@type table
+    ---LHS of operator-pending mappings in NORMAL and VISUAL mode
     opleader = {
         ---Line-comment keymap
         line = 'gc',
         ---Block-comment keymap
         block = 'gb',
     },
-
     ---LHS of extra mappings
-    ---@type table
     extra = {
         ---Add comment on the line above
         above = 'gcO',
@@ -111,29 +100,19 @@ Following are the **default** config for the [`setup()`](#setup). If you want to
         ---Add comment at the end of line
         eol = 'gcA',
     },
-
-    ---Create basic (operator-pending) and extended mappings for NORMAL + VISUAL mode
-    ---NOTE: If `mappings = false` then the plugin won't create any mappings
-    ---@type boolean|table
+    ---Enable keybindings
+    ---NOTE: If given `false` then the plugin won't create any mappings
     mappings = {
-        ---Operator-pending mapping
-        ---Includes `gcc`, `gbc`, `gc[count]{motion}` and `gb[count]{motion}`
-        ---NOTE: These mappings can be changed individually by `opleader` and `toggler` config
+        ---Operator-pending mapping; `gcc` `gbc` `gc[count]{motion}` `gb[count]{motion}`
         basic = true,
-        ---Extra mapping
-        ---Includes `gco`, `gcO`, `gcA`
+        ---Extra mapping; `gco`, `gcO`, `gcA`
         extra = true,
-        ---Extended mapping
-        ---Includes `g>`, `g<`, `g>[count]{motion}` and `g<[count]{motion}`
+        ---Extended mapping; `g>` `g<` `g>[count]{motion}` `g<[count]{motion}`
         extended = false,
     },
-
-    ---Pre-hook, called before commenting the line
-    ---@type fun(ctx: CommentCtx):string
+    ---Function to call before (un)comment
     pre_hook = nil,
-
-    ---Post-hook, called after commenting is done
-    ---@type fun(ctx: CommentCtx)
+    ---Function to call after (un)comment
     post_hook = nil,
 }
 ```
@@ -224,14 +203,6 @@ These mappings are disabled by default. (config: `mappings.extended`)
 `gbac` - Toggle comment around a class (w/ LSP/treesitter support)
 ```
 
-<a id="api"></a>
-
-### ⚙️ API
-
-- [Plug Mappings](./doc/plugs.md) - Excellent for creating custom keybindings
-
-- [Lua API](./doc/API.md) - Details the Lua API. Great for making custom comment function.
-
 <a id="treesitter"></a>
 
 ### 🌳 Treesitter
@@ -254,12 +225,10 @@ There are two hook methods i.e `pre_hook` and `post_hook` which are called befor
 
 <a id="pre-hook"></a>
 
-- `pre_hook` - This method is called with a `ctx` (Read `comment.utils.CommentCtx`) argument before comment/uncomment is started. It can be used to return a custom `commentstring` which will be used for comment/uncomment the lines. You can use something like [nvim-ts-context-commentstring](https://github.com/JoosepAlviste/nvim-ts-context-commentstring) to compute the commentstring using treesitter.
+- `pre_hook` - Called with a `ctx` argument (Read `:h comment.utils.CommentCtx`) before (un)comment. Can optionally return a `commentstring` to be used for (un)commenting. You can use [nvim-ts-context-commentstring](https://github.com/JoosepAlviste/nvim-ts-context-commentstring) to easily comment `tsx/jsx` files.
 
 ```lua
--- NOTE: The example below is a proper integration and it is RECOMMENDED.
 {
-    ---@param ctx CommentCtx
     pre_hook = function(ctx)
         -- Only calculate commentstring for tsx filetypes
         if vim.bo.filetype == 'typescriptreact' then
@@ -285,13 +254,14 @@ There are two hook methods i.e `pre_hook` and `post_hook` which are called befor
 }
 ```
 
+> **Note** - `Comment.nvim` already supports [`treesitter`](#treesitter) out-of-the-box except for `tsx/jsx`.
+
 <a id="post-hook"></a>
 
-- `post_hook` - This method is called after commenting is done. It receives the same `ctx` (Read `comment.utils.CommentCtx`) argument as [`pre_hook`](#pre_hook).
+- `post_hook` - This method is called after (un)commenting. It receives the same `ctx` (Read `:h comment.utils.CommentCtx`) argument as [`pre_hook`](#pre_hook).
 
 ```lua
 {
-    ---@param ctx CommentCtx
     post_hook = function(ctx)
         if ctx.range.srow == ctx.range.erow then
             -- do something with the current line
@@ -347,7 +317,7 @@ ignore = '^const(.*)=(%s?)%((.*)%)(%s?)=>'
 
 Most languages/filetypes have native support for comments via `commentstring` but there might be a filetype that is not supported. There are two ways to enable commenting for unsupported filetypes:
 
-1.  You can set `commentstring` for that particular filetype like the following
+1.  You can set `commentstring` for that particular filetype like the following. Read `:h commentstring` for more info.
 
 ```lua
 vim.bo.commentstring = '//%s'
@@ -356,8 +326,6 @@ vim.bo.commentstring = '//%s'
 vim.api.nvim_command('set commentstring=//%s')
 ```
 
-> Read `:h commentstring` for more help
-
 <a id="ft-lua"></a>
 
 2. You can also use this plugin interface to store both line and block commentstring for the filetype. You can treat this as a more powerful version of the `commentstring`. Read `:h comment.ft` for more info.
@@ -367,16 +335,14 @@ local ft = require('Comment.ft')
 
 -- 1. Using set function
 
--- Just set only line comment
-ft.set('yaml', '#%s')
-
--- Or set both line and block commentstring
--- You can also chain the set calls
-ft.set('javascript', {'//%s', '/*%s*/'}).set('conf', '#%s')
+ft
+ -- Set only line comment
+ .set('yaml', '#%s')
+ -- Or set both line and block commentstring
+ .set('javascript', {'//%s', '/*%s*/'})
 
 -- 2. Metatable magic
 
--- One filetype at a time
 ft.javascript = {'//%s', '/*%s*/'}
 ft.yaml = '#%s'
 

lua/Comment/api.lua

@@ -325,8 +325,6 @@ end
 ---api.toggle.blockwise.current(motion?, config?)
 ---api.toggle.blockwise.count(count, config?)
 ---
------ NORMAL mode
----
 ----- Toggle current line (linewise) using C-/
 ---vim.keymap.set('n', '<C-_>', api.toggle.linewise.current)
 ---
@@ -347,19 +345,17 @@ end
 ---    { expr = true }
 ---)
 ---
------ VISUAL mode
----
 ---local esc = vim.api.nvim_replace_termcodes(
 ---    '<ESC>', true, false, true
 ---)
 ---
------ Linewise toggle (linewise)
+----- Toggle selection (linewise)
 ---vim.keymap.set('x', '<leader>c', function()
 ---    vim.api.nvim_feedkeys(esc, 'nx', false)
 ---    api.toggle.linewise(vim.fn.visualmode())
 ---end)
 ---
------ Blockwise toggle (blockwise)
+----- Toggle selection (blockwise)
 ---vim.keymap.set('x', '<leader>b', function()
 ---    vim.api.nvim_feedkeys(esc, 'nx', false)
 ---    api.toggle.blockwise(vim.fn.visualmode())

lua/Comment/config.lua

@@ -1,24 +1,65 @@
 ---@mod comment.config Configuration
+---@tag comment.config.defaults
+---@brief [[
+---Following is the default config for the |comment.usage.setup|. If you want to
+---override, just modify the option that you want, then it will be merged with the
+---default config.
+---
+--->
+---    {
+---        padding = true,
+---        sticky = true,
+---        ignore = nil,
+---        toggler = {
+---            line = 'gcc',
+---            block = 'gbc',
+---        },
+---        opleader = {
+---            line = 'gc',
+---            block = 'gb',
+---        },
+---        extra = {
+---            above = 'gcO',
+---            below = 'gco',
+---            eol = 'gcA',
+---        },
+---        mappings = {
+---            basic = true,
+---            extra = true,
+---            extended = false,
+---        },
+---        pre_hook = nil,
+---        post_hook = nil,
+---    }
+---<
+---@brief ]]
 
 ---@class CommentConfig Plugin's configuration
 ---Controls space between the comment
 ---and the line (default: 'true')
----@field padding boolean
+---@field padding boolean|fun():boolean
 ---Whether cursor should stay at the
----same position. Only works with NORMAL
+---same position. Only works in NORMAL
 ---mode mappings (default: 'true')
 ---@field sticky boolean
 ---Lua pattern used to ignore lines
 ---during (un)comment (default: 'nil')
 ---@field ignore string|fun():string
----@field mappings Mappings|boolean
+---Enables |comment.keybindings|
+---NOTE: If given 'false', then the
+---plugin won't create any mappings
+---@field mappings Mappings|false
 ---@field toggler Toggler
 ---@field opleader Opleader
 ---@field extra ExtraMapping
----Function to call before (un)comment
+---Function to call before (un)comment.
+---It is called with a {ctx} argument
+---of type |comment.utils.CommentCtx|
 ---(default: 'nil')
 ---@field pre_hook fun(ctx):string
----Function to call after (un)comment
+---Function to call after (un)comment.
+---It is called with a {ctx} argument
+---of type |comment.utils.CommentCtx|
 ---(default: 'nil')
 ---@field post_hook fun(ctx)
 

lua/Comment/extra.lua

@@ -1,4 +1,4 @@
----@mod comment.extra Insert API
+---@mod comment.extra Extra API
 ---@brief [[
 ---Underlying functions that powers the |comment.api.insert| lua API.
 ---@brief ]]
@@ -33,7 +33,7 @@ local function ins_on_line(lnum, ctype, cfg)
 
     local srow = row + lnum
     local lcs, rcs = U.parse_cstr(cfg, ctx)
-    local padding = U.get_pad(cfg.padding)
+    local padding = U.get_pad(U.is_fn(cfg.padding))
 
     -- We need RHS of cstr, if we are doing block comments or if RHS exists
     -- because even in line comment RHS do exists for some filetypes like jsx_element, ocaml
@@ -76,7 +76,7 @@ function extra.insert_eol(ctype, cfg)
     local lcs, rcs = U.parse_cstr(cfg, ctx)
 
     local line = A.nvim_get_current_line()
-    local padding = U.get_pad(cfg.padding)
+    local padding = U.get_pad(U.is_fn(cfg.padding))
 
     -- We need RHS of cstr, if we are doing block comments or if RHS exists
     -- because even in line comment RHS do exists for some filetypes like jsx_element, ocaml

lua/Comment/init.lua

@@ -18,7 +18,7 @@
 ---@brief [[
 ---Comment.nvim is a smart and powerful comment plugin for neovim. It supports
 ---dot-repeat, counts, line ('//') and block ('/* */') comments, and can be used
----with motion and text-objects. It has native integration with tressitter to
+---with motion and text-objects. It has native integration with |tressitter| to
 ---support embedded filetypes like html, vue, markdown with codeblocks etc.
 ---@brief ]]
 ---@tag comment.dotrepeat
@@ -49,6 +49,11 @@
 ---the string in |comment.ft| instead of using 'commentstring'. To override this
 ---behavior, you have to manually return the 'commentstring' from 'pre_hook'.
 ---@brief ]]
+---@tag comment.sourcecode
+---@brief [[
+---Comment.nvim is FOSS provided under MIT license. All the source code is avaiable
+---at https://github.com/numToStr/Comment.nvim
+---@brief ]]
 
 ---@mod comment.usage Usage
 ---@brief [[
@@ -65,6 +70,10 @@ local C = {}
 ---@return CommentConfig _ Returns the mutated config
 ---@see comment.config
 ---@usage [[
+----- Use default configuration
+---require('Comment').setup()
+---
+----- or with custom configuration
 ---require('Comment').setup({
 ---    ignore = '^$',
 ---    toggler = {

lua/Comment/utils.lua

@@ -128,7 +128,7 @@ end
 
 ---Get lines from the current position to the given count
 ---@param count integer Probably 'vim.v.count'
----@return string[] List of lines
+---@return string[] _ List of lines
 ---@return CommentRange
 function U.get_count_lines(count)
     local srow = unpack(A.nvim_win_get_cursor(0))
@@ -140,7 +140,7 @@ end
 
 ---Get lines from a NORMAL/VISUAL mode
 ---@param range CommentRange
----@return string[] List of lines
+---@return string[] _ List of lines
 function U.get_lines(range)
     -- If start and end is same, then just return the current line
     if range.srow == range.erow then