chore!: refactoring (#179)

### Added
- `utils.commenter()`
- `utils.uncommenter()`

### Changed
- `utils.{unwrap_cstr,parse_cstr}()` now returns `string, string` instead of `string|bool, string|bool`
- Merged `Op.blockwise_x()` with `Op.blockwise()`
- Removed `utils.get_padding()`, `utils.move_n_insert()` and `utils.grab_indent()`
- Removed `utils.comment_str()` (Use `utils.commenter()`)
- Removed `utils.uncomment_str()` (Use `utils.uncommenter()`)
- Changed `utils.is_commented()` function signature.

Resolve #177

Author: numToStr

README.md

@@ -43,7 +43,7 @@ lua require('Comment').setup()
 
 First you need to call the `setup()` method to create the default mappings.
 
-> NOTE: If you are facing **Keybindings are mapped but they are not working** issue then please try [this](https://github.com/numToStr/Comment.nvim/issues/115#issuecomment-1032290098)
+> **Note** - If you are facing **Keybindings are mapped but they are not working** issue then please try [this](https://github.com/numToStr/Comment.nvim/issues/115#issuecomment-1032290098)
 
 - Lua
 
@@ -243,6 +243,8 @@ This plugin has native **treesitter** support for calculating `commentstring` wh
 
 For advance use cases, use [nvim-ts-context-commentstring](https://github.com/JoosepAlviste/nvim-ts-context-commentstring). See [`pre_hook`](#pre-hook) section for the integration.
 
+> **Note** - This plugin does not depend on [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) however it is recommended in order to easily install tree-sitter parsers.
+
 <a id="hooks"></a>
 
 ### 🎣 Hooks
@@ -355,6 +357,8 @@ vim.api.nvim_command('set commentstring=//%s')
 
 > Run `: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`
 
 ```lua
@@ -394,7 +398,7 @@ Although, `Comment.nvim` supports neovim's `commentstring` but unfortunately it
 
 - [`pre_hook`](#hooks) - If a string is returned from this method then it will be used for commenting.
 
-- [`ft_table`](#languages) - If the current filetype is found in the table, then the string there will be used.
+- [`ft.lua`](#ft-lua) - If the current filetype is found in the table, then the string there will be used.
 
 - `commentstring` - Neovim's native commentstring for the filetype
 
@@ -420,10 +424,10 @@ The following object is provided as an argument to `pre_hook` and `post_hook` fu
 
 ---Range of the selection that needs to be commented
 ---@class CommentRange
----@field srow number Starting row
----@field scol number Starting column
----@field erow number Ending row
----@field ecol number Ending column
+---@field srow integer Starting row
+---@field scol integer Starting column
+---@field erow integer Ending row
+---@field ecol integer Ending column
 ```
 
 `CommentType`, `CommentMode` and `CommentMotion` all of them are exported from the plugin's utils for reuse

lua/Comment/api.lua

@@ -197,7 +197,7 @@ end
 ---@param opmode OpMode
 ---@param cfg? CommentConfig
 function api.uncomment_current_blockwise_op(opmode, cfg)
-    Op.opfunc(opmode, cfg, U.cmode.uncomment, U.ctype.block, U.cmotion.line)
+    Op.opfunc(opmode, cfg or Config:get(), U.cmode.uncomment, U.ctype.block, U.cmotion.line)
 end
 
 --==========================================

lua/Comment/config.lua

@@ -44,8 +44,8 @@
 ---@private
 ---@class RootConfig
 ---@field config CommentConfig
----@field position number[] To be used to restore cursor position
----@field count number Helps with dot-repeat support for count prefix
+---@field position integer[] To be used to restore cursor position
+---@field count integer Helps with dot-repeat support for count prefix
 local Config = {
     state = {},
     config = {
@@ -88,6 +88,7 @@ function Config:get()
     return self.config
 end
 
+---@export ft
 return setmetatable(Config, {
     __index = function(this, k)
         return this.state[k]

lua/Comment/extra.lua

@@ -5,8 +5,17 @@ local A = vim.api
 
 local extra = {}
 
----@param count number Line index
----@param ctype CommentType
+-- FIXME This prints `a` in i_CTRL-o
+---Moves the cursor and enters INSERT mode
+---@param row integer Starting row
+---@param col integer Ending column
+local function move_n_insert(row, col)
+    A.nvim_win_set_cursor(0, { row, col })
+    A.nvim_feedkeys('a', 'ni', true)
+end
+
+---@param count integer Line index
+---@param ctype integer
 ---@param cfg CommentConfig
 local function ins_on_line(count, ctype, cfg)
     local row, col = unpack(A.nvim_win_get_cursor(0))
@@ -18,40 +27,39 @@ local function ins_on_line(count, ctype, cfg)
         ctype = ctype,
         range = { srow = row, scol = col, erow = row, ecol = col },
     }
-    local lcs, rcs = U.parse_cstr(cfg, ctx)
 
+    local srow = row + count
+    local lcs, rcs = U.parse_cstr(cfg, ctx)
     local line = A.nvim_get_current_line()
-    local indent = U.grab_indent(line)
-    local padding = U.get_padding(cfg.padding)
+    local indent = U.indent_len(line)
+    local padding = U.get_pad(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
-    local if_rcs = (ctype == U.ctype.block or rcs) and padding .. rcs or ''
+    local if_rcs = U.is_empty(rcs) and rcs or padding .. rcs
 
-    local srow = row + count
-    local ll = indent .. lcs .. padding
-    A.nvim_buf_set_lines(0, srow, srow, false, { ll .. if_rcs })
-    local erow, ecol = srow + 1, #ll - 1
-    U.move_n_insert(erow, ecol)
+    A.nvim_buf_set_lines(0, srow, srow, false, { table.concat({ string.rep(' ', indent), lcs, padding, if_rcs }) })
+
+    move_n_insert(srow + 1, indent + #lcs + #padding - 1)
     U.is_fn(cfg.post_hook, ctx)
 end
 
 ---Add a comment below the current line and goes to INSERT mode
----@param ctype CommentType
+---@param ctype integer See |comment.utils.ctype|
 ---@param cfg CommentConfig
 function extra.insert_below(ctype, cfg)
     ins_on_line(0, ctype, cfg)
 end
 
 ---Add a comment above the current line and goes to INSERT mode
----@param ctype CommentType
+---@param ctype integer See |comment.utils.ctype|
 ---@param cfg CommentConfig
 function extra.insert_above(ctype, cfg)
     ins_on_line(-1, ctype, cfg)
 end
 
 ---Add a comment at the end of current line and goes to INSERT mode
----@param ctype CommentType
+---@param ctype integer See |comment.utils.ctype|
 ---@param cfg CommentConfig
 function extra.insert_eol(ctype, cfg)
     local srow, scol = unpack(A.nvim_win_get_cursor(0))
@@ -66,16 +74,16 @@ 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_padding(cfg.padding)
+    local padding = U.get_pad(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
-    local if_rcs = rcs and padding .. rcs or ''
+    local if_rcs = U.is_empty(rcs) and rcs or padding .. rcs
 
     local ecol
     if U.is_empty(line) then
         -- If line is empty, start comment at the correct indentation level
-        A.nvim_buf_set_lines(0, srow - 1, srow, false, { lcs .. padding .. if_rcs })
+        A.nvim_set_current_line(lcs .. padding .. if_rcs)
         A.nvim_command('normal! ==')
         ecol = #A.nvim_get_current_line() - #if_rcs - 1
     else
@@ -84,12 +92,11 @@ function extra.insert_eol(ctype, cfg)
         -- 2. Other than that, I am assuming that the users wants a space b/w the end of line and start of the comment
         local space = vim.bo.filetype == 'python' and '  ' or ' '
         local ll = line .. space .. lcs .. padding
-
+        A.nvim_set_current_line(ll .. if_rcs)
         ecol = #ll - 1
-        A.nvim_buf_set_lines(0, srow - 1, srow, false, { ll .. if_rcs })
     end
 
-    U.move_n_insert(srow, ecol)
+    move_n_insert(srow, ecol)
     U.is_fn(cfg.post_hook, ctx)
 end
 

lua/Comment/ft.lua

@@ -19,7 +19,8 @@ local M = {
 }
 
 ---Lang table that contains commentstring (linewise/blockwise) for mutliple filetypes
----@type table { filetype = { linewise, blockwise } }
+---Structure = { filetype = { linewise, blockwise } }
+---@type table<string,string[]>
 local L = {
     arduino = { M.cxx_l, M.cxx_b },
     bash = { M.hash },
@@ -115,7 +116,7 @@ end
 
 ---Get a commentstring from the filtype list
 ---@param lang CommentLang
----@param ctype CommentType
+---@param ctype integer See |comment.utils.ctype|
 ---@return string
 function ft.get(lang, ctype)
     local l = ft.lang(lang)
@@ -124,16 +125,16 @@ end
 
 ---Get the commentstring(s) from the filtype list
 ---@param lang CommentLang
----@return string
+---@return string[]
 function ft.lang(lang)
     return L[lang]
 end
 
 ---Get the tree in range by walking the whole tree recursively
----NOTE: This ignores `comment` parser as this is useless
+---NOTE: This ignores `comment` parser as this is not needed
 ---@param tree userdata Tree to be walked
----@param range number[] Range to check for
----@return userdata
+---@param range integer[] Range to check - {start_line, s_col, end_line, end_col}
+---@return userdata _ Returns a 'treesitter-languagetree'
 function ft.contains(tree, range)
     for lang, child in pairs(tree:children()) do
         if lang ~= 'comment' and child:contains(range) then
@@ -166,6 +167,7 @@ function ft.calculate(ctx)
     return ft.get(lang, ctx.ctype) or default
 end
 
+---@export ft
 return setmetatable(ft, {
     __newindex = function(this, k, v)
         this.set(k, v)