feat: help docs :h comment-nvim

Author: numToStr

doc/plugs.md

@@ -1,34 +1 @@
-## 🔌 Plug Mappings
-
-Following are the `<Plug>` mappings which you can use to quickly setup your custom keybindings
-
-- `<Plug>(comment_toggle_linewise)` - Toggles line comment via Operator pending mode
-- `<Plug>(comment_toggle_blockwise)` - Toggles block comment via Operator pending mode
-- `<Plug>(comment_toggle_linewise_current)` - Toggles line comment on the current line
-- `<Plug>(comment_toggle_blockwise_current)` - Toggles block comment on the current line
-- `<Plug>(comment_toggle_linewise_count)` - Toggles line comment with count
-- `<Plug>(comment_toggle_blockwise_count)` - Toggles block comment with count
-- `<Plug>(comment_toggle_linewise_visual)` - Toggles line comment in VISUAL mode
-- `<Plug>(comment_toggle_blockwise_visual)` - Toggles block comment in VISUAL mode
-
-> NOTE: There are only meant for custom keybindings but If you want to create a custom comment function then be sure to check out all the [API](./API.md).
-
-#### Usage
-
-Following snippets is same as the default mappings set by the plugin.
-
-```lua
-local opt = { expr = true, remap = true, replace_keycodes = false }
-
--- Toggle using count
-vim.keymap.set('n', 'gcc', "v:count == 0 ? '<Plug>(comment_toggle_linewise_current)' : '<Plug>(comment_toggle_linewise_count)'", opt)
-vim.keymap.set('n', 'gbc', "v:count == 0 ? '<Plug>(comment_toggle_blockwise_current)' : '<Plug>(comment_toggle_blockwise_count)'", opt)
-
--- Toggle in Op-pending mode
-vim.keymap.set('n', 'gc', '<Plug>(comment_toggle_linewise)')
-vim.keymap.set('n', 'gb', '<Plug>(comment_toggle_blockwise)')
-
--- Toggle in VISUAL mode
-vim.keymap.set('x', 'gc', '<Plug>(comment_toggle_linewise_visual)')
-vim.keymap.set('x', 'gb', '<Plug>(comment_toggle_blockwise_visual)')
-```
+`Comment.nvim` now has `:help` docs 🎉. Check `:h comment.plugmap` for the `<Plug>` mappings documentation and usage.

dump.lua

@@ -303,56 +303,60 @@ end
 ---
 ---Following are the API functions that are available:
 ---
----require('Comment.api').toggle.linewise({motion}, {cfg?})
----require('Comment.api').toggle.linewise.current({motion?}, {cfg?})
----require('Comment.api').toggle.linewise.count({count}, {cfg?})
+---  require('Comment.api').toggle.linewise({motion}, {cfg?})
+---  require('Comment.api').toggle.linewise.current({motion?}, {cfg?})
+---  require('Comment.api').toggle.linewise.count({count}, {cfg?})
 ---
----require('Comment.api').toggle.blockwise({motion}, {cfg?})
----require('Comment.api').toggle.blockwise.current({motion?}, {cfg?})
----require('Comment.api').toggle.blockwise.count({count}, {cfg?})
+---  require('Comment.api').toggle.blockwise({motion}, {cfg?})
+---  require('Comment.api').toggle.blockwise.current({motion?}, {cfg?})
+---  require('Comment.api').toggle.blockwise.count({count}, {cfg?})
 ---@type table A metatable containing API functions
+---@see comment.config
 api.toggle = setmetatable({ cmode = U.cmode.toggle }, core)
 
 ---API to (only) comment using line or block comment string
 ---
 ---Following are the API functions that are available:
 ---
----require('Comment.api').comment.linewise({motion}, {cfg?})
----require('Comment.api').comment.linewise.current({motion?}, {cfg?})
----require('Comment.api').comment.linewise.count({count}, {cfg?})
+---  require('Comment.api').comment.linewise({motion}, {cfg?})
+---  require('Comment.api').comment.linewise.current({motion?}, {cfg?})
+---  require('Comment.api').comment.linewise.count({count}, {cfg?})
 ---
----require('Comment.api').comment.blockwise({motion}, {cfg?})
----require('Comment.api').comment.blockwise.current({motion?}, {cfg?})
----require('Comment.api').comment.blockwise.count({count}, {cfg?})
+---  require('Comment.api').comment.blockwise({motion}, {cfg?})
+---  require('Comment.api').comment.blockwise.current({motion?}, {cfg?})
+---  require('Comment.api').comment.blockwise.count({count}, {cfg?})
 ---@type table A metatable containing API functions
+---@see comment.config
 api.comment = setmetatable({ cmode = U.cmode.comment }, core)
 
 ---API to (only) uncomment using line or block comment string
 ---
 ---Following are the API functions that are available:
 ---
----require('Comment.api').uncomment.linewise({motion}, {cfg?})
----require('Comment.api').uncomment.linewise.current({motion?}, {cfg?})
----require('Comment.api').uncomment.linewise.count({count}, {cfg?})
+---  require('Comment.api').uncomment.linewise({motion}, {cfg?})
+---  require('Comment.api').uncomment.linewise.current({motion?}, {cfg?})
+---  require('Comment.api').uncomment.linewise.count({count}, {cfg?})
 ---
----require('Comment.api').uncomment.blockwise({motion}, {cfg?})
----require('Comment.api').uncomment.blockwise.current({motion?}, {cfg?})
----require('Comment.api').uncomment.blockwise.count({count}, {cfg?})
+---  require('Comment.api').uncomment.blockwise({motion}, {cfg?})
+---  require('Comment.api').uncomment.blockwise.current({motion?}, {cfg?})
+---  require('Comment.api').uncomment.blockwise.count({count}, {cfg?})
 ---@type table A metatable containing API functions
+---@see comment.config
 api.uncomment = setmetatable({ cmode = U.cmode.comment }, core)
 
 ---API to insert comment on previous, next or at the end-of-line
 ---
 ---Following are the API functions that are available:
 ---
----require('Comment.api').insert.linewise.above({cfg?})
----require('Comment.api').insert.linewise.below({cfg?})
----require('Comment.api').insert.linewise.eol({cfg?})
+---  require('Comment.api').insert.linewise.above({cfg?})
+---  require('Comment.api').insert.linewise.below({cfg?})
+---  require('Comment.api').insert.linewise.eol({cfg?})
 ---
----require('Comment.api').insert.blockwise.above({cfg?})
----require('Comment.api').insert.blockwise.below({cfg?})
----require('Comment.api').insert.blockwise.eol({cfg?})
+---  require('Comment.api').insert.blockwise.above({cfg?})
+---  require('Comment.api').insert.blockwise.below({cfg?})
+---  require('Comment.api').insert.blockwise.eol({cfg?})
 ---@type table A metatable containing API functions
+---@see comment.config
 api.insert = setmetatable({}, {
     __index = function(_, ctype)
         return {
@@ -369,17 +373,29 @@ api.insert = setmetatable({}, {
     end,
 })
 
----Wraps a given function with `lockmarks` to preserve marks/jumps when commenting
+-- TODO: After removing old API
+-- 1. make `api.locked` a simple function call
+-- 2. fix emmylua doc
+
+---Wraps the given API function name with `lockmarks` to preserve marks/jumps
 ---@type fun(cb:string):fun(motion:OpMotion)
----@usage `require('Comment.api').locked('toggle.linewise.current')()`
+---@see lockmarks
+---@usage [[
+---local api = require('Comment.api')
+---vim.keymap.set(
+---    'n', '<leader>c', api.locked('toggle.linewise.current')
+---)
+---vim.keymap.set(
+---    'n', '<leader>o', api.locked('insert.linewise.below')
+---)
+---@usage ]]
 api.locked = setmetatable({}, {
     __index = function(this, cb)
         D(string.format('locker.%s(args...)', cb), string.format('locked(%q)(args...)', cb))
         return this(cb)
     end,
-    -- TODO: After removal of the old api functions, make `api.locked` a simple function call
     __call = function(_, cb)
-        ---Actual function which will be attached to operatorfunc
+        ---operatorfunc callback
         ---@param motion OpMotion
         return function(motion)
             return A.nvim_command(
@@ -390,13 +406,23 @@ api.locked = setmetatable({}, {
 })
 
 ---Callback function which does the following
----  1. Sets operatorfunc for dot-repeat
+---  1. Sets 'operatorfunc' for dot-repeat
 ---  2. Preserves jumps and marks
 ---  3. Stores last cursor position
 ---@param cb string Name of the API function to call
 ---@param op 'g@'|'g@$' Operator string to execute
 ---@return fun():string _ Keymap RHS callback
----@usage `vim.keymap.set('n', 'gc', api.call('toggle.linewise', 'g@'), { expr = true })`
+---@usage [[
+---local api = require('Comment.api')
+---vim.keymap.set(
+---    'n', 'gc', api.call('toggle.linewise', 'g@'),
+---    { expr = true }
+---)
+---vim.keymap.set(
+---    'n', 'gcc', api.call('toggle.linewise.current', 'g@$'),
+---    { expr = true }
+---)
+---@usage ]]
 function api.call(cb, op)
     return function()
         A.nvim_set_option('operatorfunc', ("v:lua.require'Comment.api'.locked'%s'"):format(cb))

lua/Comment/api.lua

@@ -1,45 +1,51 @@
 ---@mod comment.config Configuration
 
----@class Toggler LHS of toggle mappings in NORMAL + VISUAL mode
----@field line string Linewise comment keymap
----@field block string Blockwise comment keymap
-
----@class Opleader LHS of operator-mode mappings in NORMAL + VISUAL mode
----@field line string Linewise comment keymap
----@field block string Blockwise comment keymap
-
----@class ExtraMapping LHS of extra mappings
----@field above string Mapping to add comment on the line above
----@field below string Mapping to add comment on the line below
----@field eol string Mapping to add comment at the end of line
-
----@class Mappings Create default mappings
----Enable 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
----@field basic boolean
----Enable extra mapping
----Includes `gco`, `gcO`, `gcA`
----@field extra boolean
----Enable extended mapping
----Includes `g>`, `g<`, `g>[count]{motion}` and `g<[count]{motion}`
----@field extended boolean
-
 ---@class CommentConfig Plugin's configuration
----@field padding boolean Add a space b/w comment and the line
----Whether the cursor should stay at its position
----NOTE: This only affects NORMAL mode mappings and doesn't work with dot-repeat
+---Controls space between the comment
+---and the line (default: 'true')
+---@field padding boolean
+---Whether cursor should stay at the
+---same position. Only works with NORMAL
+---mode mappings (default: 'true')
 ---@field sticky boolean
----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
+---Lua pattern used to ignore lines
+---during (un)comment (default: 'nil')
 ---@field ignore string|fun():string
----@field mappings boolean|Mappings
+---@field mappings Mappings|boolean
 ---@field toggler Toggler
 ---@field opleader Opleader
 ---@field extra ExtraMapping
----@field pre_hook fun(ctx:CommentCtx):string Function to be called before comment/uncomment
----@field post_hook fun(ctx:CommentCtx) Function to be called after comment/uncomment
+---Function to call before (un)comment
+---(default: 'nil')
+---@field pre_hook fun(ctx):string
+---Function to call after (un)comment
+---(default: 'nil')
+---@field post_hook fun(ctx)
+
+---@class Mappings Create default mappings
+---Enables operator-pending mapping; `gcc`, `gbc`,
+---`gc{motion}` and `gb{motion}` (default: 'true')
+---@field basic boolean
+---Enable extra mapping; `gco`, `gcO` and `gcA`
+---(default: 'true')
+---@field extra boolean
+---Enable extended mapping; `g>`, `g<c`, 'g<b',
+---'g<', 'g<c', 'g<b', `g>{motion}` and `g<{motion}`
+---(default: 'false')
+---@field extended boolean
+
+---@class Toggler LHS of toggle mappings in NORMAL
+---@field line string Linewise comment (default: 'gcc')
+---@field block string Blockwise comment (default: 'gbc')
+
+---@class Opleader LHS of operator-mode mappings in NORMAL and VISUAL mode
+---@field line string Linewise comment (default: 'gc')
+---@field block string Blockwise comment (default: 'gb')
+
+---@class ExtraMapping LHS of extra mappings
+---@field below string Inserts comment below (default: 'gco')
+---@field above string Inserts comment above (default: 'gcO')
+---@field eol string Inserts comment at the end of line (default: 'gcA')
 
 ---@private
 ---@class RootConfig
@@ -72,9 +78,12 @@ local Config = {
     },
 }
 
----Update the config
+---@private
+---Updates the default config
 ---@param cfg? CommentConfig
 ---@return RootConfig
+---@see comment.usage.setup
+---@usage `require('Comment.config'):set({config})`
 function Config:set(cfg)
     if cfg then
         self.config = vim.tbl_deep_extend('force', self.config, cfg)
@@ -84,11 +93,12 @@ end
 
 ---Get the config
 ---@return CommentConfig
+---@usage `require('Comment.config'):get()`
 function Config:get()
     return self.config
 end
 
----@export ft
+---@export Config
 return setmetatable(Config, {
     __index = function(this, k)
         return this.state[k]