little emmylua tweaks

Author: numToStr

README.md

@@ -424,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/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

@@ -7,15 +7,15 @@ local extra = {}
 
 -- FIXME This prints `a` in i_CTRL-o
 ---Moves the cursor and enters INSERT mode
----@param row number Starting row
----@param col number Ending column
+---@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 number Line index
----@param ctype number See |CommentType|
+---@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))
@@ -45,21 +45,21 @@ local function ins_on_line(count, ctype, cfg)
 end
 
 ---Add a comment below the current line and goes to INSERT mode
----@param ctype number See |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 number See |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 number See |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))

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 number See |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)

lua/Comment/opfunc.lua

@@ -6,18 +6,24 @@ local A = vim.api
 
 local Op = {}
 
----@alias OpMode 'line'|'char'|'v'|'V' Vim operator-mode motions. Read `:h map-operator`
+---Vim operator-mode motions.
+---Read `:h :map-operator`
+---@alias OpMode
+---| 'line' # Vertical motion
+---| 'char' # Horizontal motion
+---| 'v' # Visual Block motion
+---| 'V' # Visual Line motion
 
 ---@class CommentCtx Comment context
----@field ctype number CommentType
----@field cmode number CommentMode
----@field cmotion number CommentMotion
+---@field ctype integer See |comment.utils.ctype|
+---@field cmode integer See |comment.utils.cmode|
+---@field cmotion integer See |comment.utils.cmotion|
 ---@field range CommentRange
 
 ---@class OpFnParams Operator-mode function parameters
 ---@field cfg CommentConfig
----@field cmode number See |comment.utils.cmode|
----@field lines table List of lines
+---@field cmode integer See |comment.utils.cmode|
+---@field lines string[] List of lines
 ---@field rcs string RHS of commentstring
 ---@field lcs string LHS of commentstring
 ---@field range CommentRange
@@ -26,28 +32,10 @@ local Op = {}
 ---This function contains the core logic for comment/uncomment
 ---@param opmode OpMode
 ---@param cfg CommentConfig
----@param cmode number CommentMode
----@param ctype number CommentType
----@param cmotion number CommentMotion
+---@param cmode integer See |comment.utils.cmode|
+---@param ctype integer See |comment.utils.ctype|
+---@param cmotion integer See |comment.utils.cmotion|
 function Op.opfunc(opmode, cfg, cmode, ctype, cmotion)
-    -- comment/uncomment logic
-    --
-    -- 1. type == line
-    --      * decide whether to comment or not, if all the lines are commented then uncomment otherwise comment
-    --      * also, store the minimum indent from all the lines (exclude empty line)
-    --      * if comment the line, use cstr LHS and also considering the min indent
-    --      * if uncomment the line, remove cstr LHS from lines
-    --      * update the lines
-    -- 2. type == block
-    --      * check if the first and last is commented or not with cstr LHS and RHS respectively.
-    --      * if both lines commented
-    --          - remove cstr LHS from the first line
-    --          - remove cstr RHS to end of the last line
-    --      * if both lines uncommented
-    --          - add cstr LHS after the leading whitespace and before the first char of the first line
-    --          - add cstr RHS to end of the last line
-    --      * update the lines
-
     cmotion = cmotion == U.cmotion._ and U.cmotion[opmode] or cmotion
 
     local range = U.get_region(opmode)
@@ -103,7 +91,7 @@ end
 
 ---Line commenting
 ---@param param OpFnParams
----@return number
+---@return integer _ Returns a calculated comment mode
 function Op.linewise(param)
     local pattern = U.is_fn(param.cfg.ignore)
     local padding = U.is_fn(param.cfg.padding)
@@ -161,10 +149,10 @@ function Op.linewise(param)
     return cmode
 end
 
----Full/Partial/Current-line Block commenting
+---Full/Partial/Current-Line Block commenting
 ---@param param OpFnParams
 ---@param partial? boolean Comment the partial region (visual mode)
----@return number
+---@return integer _ Returns a calculated comment mode
 function Op.blockwise(param, partial)
     local is_x = #param.lines == 1 -- current-line blockwise
     local lines = is_x and param.lines[1] or param.lines
@@ -198,11 +186,11 @@ function Op.blockwise(param, partial)
     return cmode
 end
 
----Toggle line comment with count i.e vim.v.count
----Example: `10gl` will comment 10 lines
----@param count number Number of lines
+---Line commenting with count i.e vim.v.count
+---Example: '10gl' will comment 10 lines
+---@param count integer Number of lines
 ---@param cfg CommentConfig
----@param ctype number CommentType
+---@param ctype integer See |comment.utils.ctype|
 function Op.count(count, cfg, ctype)
     local lines, range = U.get_count_lines(count)
 

lua/Comment/utils.lua

@@ -37,12 +37,12 @@ U.ctype = {
 }
 
 ---@class CommentMotion Comment motion types
----@field private _ number Compute from vim mode. See |OpMode|
----@field line number Line motion (ie. `gc2j`)
----@field char number Character/left-right motion (ie. `gc2j`)
----@field block number Visual operator-pending motion
----@field v number Visual motion
----@field V number Visual-line motion
+---@field private _ integer Compute from vim mode. See |OpMode|
+---@field line integer Line motion (ie. 'gc2j')
+---@field char integer Character/left-right motion (ie. 'gc2w')
+---@field block integer Visual operator-pending motion
+---@field v integer Visual motion (ie. 'v3jgc')
+---@field V integer Visual-line motion (ie. 'V10kgc')
 
 ---An object containing comment motions
 ---@type CommentMotion
@@ -55,13 +55,15 @@ U.cmotion = {
     V = 5,
 }
 
+---@private
 ---Check whether the line is empty
 ---@param iter string|string[]
 ---@return boolean
 function U.is_empty(iter)
     return #iter == 0
 end
 
+---@private
 ---Get the length of the indentation
 ---@param str string
 ---@return integer integer Length of indent chars
@@ -97,6 +99,7 @@ function U.is_fn(fn, ...)
     return fn
 end
 
+---@private
 ---Check if the given line is ignored or not with the given pattern
 ---@param ln string Line to be ignored
 ---@param pat string Lua regex
@@ -122,7 +125,7 @@ function U.get_region(opmode)
 end
 
 ---Get lines from the current position to the given count
----@param count number
+---@param count integer Probably 'vim.v.count'
 ---@return CommentLines
 ---@return CommentRange
 function U.get_count_lines(count)
@@ -146,7 +149,7 @@ function U.get_lines(range)
 end
 
 ---Validates and unwraps the given commentstring
----@param cstr string
+---@param cstr string See 'commentstring'
 ---@return string string Left side of the commentstring
 ---@return string string Right side of the commentstring
 function U.unwrap_cstr(cstr)
@@ -160,10 +163,10 @@ function U.unwrap_cstr(cstr)
     return vim.trim(left), vim.trim(right)
 end
 
----Unwraps the commentstring by taking it from the following places
----     1. `pre_hook` (optionally a string can be returned)
----     2. `ft.lua` (extra commentstring table in the plugin)
----     3. `commentstring` (already set or added in pre_hook)
+---Parses commentstring from the following places in the respective order
+---  1. pre_hook - commentstring returned from the function
+---  2. ft.lua - commentstring table bundled with the plugin
+---  3. commentstring - Neovim's native. See 'commentstring'
 ---@param cfg CommentConfig
 ---@param ctx CommentCtx
 ---@return string string Left side of the commentstring
@@ -179,9 +182,10 @@ function U.parse_cstr(cfg, ctx)
     return U.unwrap_cstr(cstr)
 end
 
----Returns a closure which is used to comment a line
----If given {string[]} to the closure then it will do blockwise
----else it will do linewise
+---Returns a closure which is used to do comments
+---
+---If given {string[]} to the closure then it will do blockwise comment
+---else linewise comment will be done with the given {string}
 ---@param left string Left side of the commentstring
 ---@param right string Right side of the commentstring
 ---@param padding boolean Is padding enabled?
@@ -243,6 +247,9 @@ function U.commenter(left, right, padding, scol, ecol)
 end
 
 ---Returns a closure which is used to uncomment a line
+---
+---If given {string[]} to the closure then it will block uncomment
+---else linewise uncomment will be done with the given {string}
 ---@param left string Left side of the commentstring
 ---@param right string Right side of the commentstring
 ---@param padding boolean Is padding enabled?
@@ -299,6 +306,10 @@ function U.uncommenter(left, right, padding, scol, ecol)
 end
 
 ---Check if the given string is commented or not
+---
+---If given {string[]} to the closure, it will check the first and last line
+---with LHS and RHS of commentstring respectively else it will check the given
+---line with LHS and RHS (if given) of the commenstring
 ---@param left string Left side of the commentstring
 ---@param right string Right side of the commentstring
 ---@param padding boolean Is padding enabled?