little emmylua tweaks

Author: numToStr

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 = {
     bash = { M.hash },
     bib = { M.latex },
@@ -123,7 +124,7 @@ end
 
 ---Get the commentstring(s) from the filtype list
 ---@param lang CommentLang
----@return string
+---@return string[]
 function ft.lang(lang)
     return L[lang]
 end
@@ -132,7 +133,7 @@ end
 ---NOTE: This ignores `comment` parser as this is useless
 ---@param tree userdata Tree to be walked
 ---@param range number[] Range to check for
----@return userdata
+---@return userdata _ See `:h treesitter-languagetree`
 function ft.contains(tree, range)
     for lang, child in pairs(tree:children()) do
         if lang ~= 'comment' and child:contains(range) then

lua/Comment/opfunc.lua

@@ -6,7 +6,13 @@ 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
@@ -30,24 +36,6 @@ local Op = {}
 ---@param ctype number CommentType
 ---@param cmotion number CommentMotion
 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)
@@ -161,7 +149,7 @@ 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
@@ -198,8 +186,8 @@ function Op.blockwise(param, partial)
     return cmode
 end
 
----Toggle line comment with count i.e vim.v.count
----Example: `10gl` will comment 10 lines
+---Line commenting with count i.e vim.v.count
+---Example: '10gl' will comment 10 lines
 ---@param count number Number of lines
 ---@param cfg CommentConfig
 ---@param ctype number CommentType

lua/Comment/utils.lua

@@ -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
@@ -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 `:h '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?