chore!: error handling (#285)

This adds error handling to the plugin, implemented with the help of
`assert` and `xpcall`. Adding explicit error handling for the following
cases for now:

- Invalid commenstring / Commenting is not supported like `json`
- When filetype doesn't support block comments like `yaml`
- Graceful handling of certain cases like uncommenting when there is
nothing to uncomment.

---

fixes #221 
supersedes #277

Author: numToStr

lua/Comment/api.lua

@@ -13,6 +13,10 @@ local A = vim.api
 
 local api, core = {}, {}
 
+---API metamethods
+---@param that table
+---@param ctype CommentType
+---@return table
 function core.__index(that, ctype)
     local idxd = {}
     local mode, type = that.cmode, U.ctype[ctype]
@@ -22,25 +26,25 @@ function core.__index(that, ctype)
     ---In current-line linewise method, 'opmode' is not useful which is always equals to `char`
     ---but we need 'nil' here which is used for current-line
     function idxd.current(_, cfg)
-        Op.opfunc(nil, cfg or Config:get(), mode, type)
+        U.catch(Op.opfunc, nil, cfg or Config:get(), mode, type)
     end
 
     ---To comment lines with a count
     function idxd.count(count, cfg)
-        Op.count(count or A.nvim_get_vvar('count'), cfg or Config:get(), mode, type)
+        U.catch(Op.count, count or A.nvim_get_vvar('count'), cfg or Config:get(), mode, type)
     end
 
     ---@private
     ---To comment lines with a count, also dot-repeatable
-    ---WARNING: This is not part of the API but anyone case use it, if they want
+    ---WARN: This is not part of the API but anyone case use it, if they want
     function idxd.count_repeat(_, count, cfg)
         idxd.count(count, cfg)
     end
 
     return setmetatable({}, {
         __index = idxd,
         __call = function(_, motion, cfg)
-            Op.opfunc(motion, cfg or Config:get(), mode, type)
+            U.catch(Op.opfunc, motion, cfg or Config:get(), mode, type)
         end,
     })
 end
@@ -173,13 +177,13 @@ api.insert = setmetatable({}, {
     __index = function(_, ctype)
         return {
             above = function(cfg)
-                Ex.insert_above(U.ctype[ctype], cfg or Config:get())
+                U.catch(Ex.insert_above, U.ctype[ctype], cfg or Config:get())
             end,
             below = function(cfg)
-                Ex.insert_below(U.ctype[ctype], cfg or Config:get())
+                U.catch(Ex.insert_below, U.ctype[ctype], cfg or Config:get())
             end,
             eol = function(cfg)
-                Ex.insert_eol(U.ctype[ctype], cfg or Config:get())
+                U.catch(Ex.insert_eol, U.ctype[ctype], cfg or Config:get())
             end,
         }
     end,

lua/Comment/ft.lua

@@ -193,7 +193,12 @@ function ft.get(lang, ctype)
     if not ctype then
         return vim.deepcopy(tuple)
     end
-    return tuple[ctype]
+    local cmt_str = tuple[ctype]
+    assert(
+        cmt_str or (ctype ~= require('Comment.utils').ctype.blockwise),
+        { msg = lang .. " doesn't support block comments!" }
+    )
+    return cmt_str
 end
 
 ---Get a language tree for a given range by walking the parse tree recursively.

lua/Comment/opfunc.lua

@@ -171,14 +171,14 @@ function Op.linewise(param)
         local uncomment = U.uncommenter(param.lcs, param.rcs, padding)
         for i, line in ipairs(param.lines) do
             if not U.ignore(line, pattern) then
-                param.lines[i] = uncomment(line)
+                param.lines[i] = uncomment(line) --[[@as string]]
             end
         end
     else
         local comment = U.commenter(param.lcs, param.rcs, padding, min_indent, nil, tabbed)
         for i, line in ipairs(param.lines) do
             if not U.ignore(line, pattern) then
-                param.lines[i] = comment(line)
+                param.lines[i] = comment(line) --[[@as string]]
             end
         end
     end

lua/Comment/utils.lua

@@ -1,6 +1,5 @@
 ---@mod comment.utils Utilities
 
-local F = require('Comment.ft')
 local A = vim.api
 
 local U = {}
@@ -89,7 +88,7 @@ end
 
 ---@private
 ---Call a function if exists
----@param fn unknown|fun():unknown Wanna be function
+---@param fn unknown|fun(...):unknown Wanna be function
 ---@return unknown
 function U.is_fn(fn, ...)
     if type(fn) == 'function' then
@@ -156,7 +155,7 @@ function U.unwrap_cstr(cstr)
 
     assert(
         (left or right),
-        string.format("[Comment] Invalid commentstring - %q. Run ':h commentstring' for help.", cstr)
+        { msg = string.format('Invalid commentstring for %s! Read `:h commentstring` for help.', vim.bo.filetype) }
     )
 
     return vim.trim(left), vim.trim(right)
@@ -174,7 +173,7 @@ function U.parse_cstr(cfg, ctx)
     -- 1. We ask `pre_hook` for a commentstring
     local cstr = U.is_fn(cfg.pre_hook, ctx)
         -- 2. Calculate w/ the help of treesitter
-        or F.calculate(ctx)
+        or require('Comment.ft').calculate(ctx)
         -- 3. Last resort to use native commentstring
         or vim.bo.commentstring
 
@@ -211,8 +210,8 @@ function U.commenter(left, right, padding, scol, ecol, tabbed)
             if scol == 0 then
                 return (ll .. line .. rr)
             end
-            local first = string.sub(line, 0, scol)
-            local last = string.sub(line, scol + 1, -1)
+            local first = string.sub(line --[[@as string]], 0, scol)
+            local last = string.sub(line --[[@as string]], scol + 1, -1)
             return first .. ll .. last .. rr
         end
 
@@ -294,6 +293,8 @@ function U.uncommenter(left, right, padding, scol, ecol)
         ------------------
         if is_lw then
             local a, b, c = string.match(line, pattern)
+            -- When user tries to uncomment when there is nothing to uncomment. See #221
+            assert(a and b, { msg = 'Nothing to uncomment!' })
             -- If there is nothing after LHS then just return ''
             -- bcz the line previously (before comment) was empty
             return U.is_empty(b) and b or a .. b .. (c or '')
@@ -359,4 +360,13 @@ function U.is_commented(left, right, padding, scol, ecol)
     end
 end
 
+---@private
+---Error handler
+---@param ... unknown
+function U.catch(fn, ...)
+    xpcall(fn, function(err)
+        vim.notify(string.format('[Comment.nvim] %s', err.msg), vim.log.levels.WARN)
+    end, ...)
+end
+
 return U