feat: help docs :h comment-nvim

Author: numToStr

README.md

@@ -254,7 +254,7 @@ There are two hook methods i.e `pre_hook` and `post_hook` which are called befor
 
 <a id="pre-hook"></a>
 
-- `pre_hook` - This method is called with a [`ctx`](#comment-context) argument before comment/uncomment is started. It can be used to return a custom `commentstring` which will be used for comment/uncomment the lines. You can use something like [nvim-ts-context-commentstring](https://github.com/JoosepAlviste/nvim-ts-context-commentstring) to compute the commentstring using treesitter.
+- `pre_hook` - This method is called with a `ctx` (Read `comment.utils.CommentCtx`) argument before comment/uncomment is started. It can be used to return a custom `commentstring` which will be used for comment/uncomment the lines. You can use something like [nvim-ts-context-commentstring](https://github.com/JoosepAlviste/nvim-ts-context-commentstring) to compute the commentstring using treesitter.
 
 ```lua
 -- NOTE: The example below is a proper integration and it is RECOMMENDED.
@@ -287,7 +287,7 @@ There are two hook methods i.e `pre_hook` and `post_hook` which are called befor
 
 <a id="post-hook"></a>
 
-- `post_hook` - This method is called after commenting is done. It receives the same [`ctx`](#comment-context) argument as [`pre_hook`](#pre_hook).
+- `post_hook` - This method is called after commenting is done. It receives the same `ctx` (Read `comment.utils.CommentCtx`) argument as [`pre_hook`](#pre_hook).
 
 ```lua
 {
@@ -407,40 +407,6 @@ Although, `Comment.nvim` supports neovim's `commentstring` but unfortunately it
 
 > There is one caveat with this approach. If someone sets the `commentstring` (w/o returning a string) from the `pre_hook` method and if the current filetype also exists in the `ft_table` then the commenting will be done using the string in `ft_table` instead of using `commentstring`
 
-<a id="comment-context"></a>
-
-### 🧠 Comment Context
-
-The following object is provided as an argument to `pre_hook` and `post_hook` functions.
-
-> I am just placing it here just for documentation purpose
-
-```lua
----Comment context
----@class CommentCtx
----@field ctype CommentType
----@field cmode CommentMode
----@field cmotion CommentMotion
----@field range CommentRange
-
----Range of the selection that needs to be commented
----@class CommentRange
----@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
-require('Comment.utils').ctype.{linewise,blockwise}
-
-require('Comment.utils').cmode.{toggle,comment,uncomment}
-
-require('Comment.utils').cmotion.{line,char,v,V}
-```
-
 ### 🤝 Contributing
 
 There are multiple ways to contribute reporting/fixing bugs, feature requests. You can also submit commentstring to this plugin by updating [ft.lua](./lua/Comment/ft.lua) and sending PR.

doc/API.md

@@ -1,227 +1 @@
-# ⚙️ API
-
-Following are list of APIs that are exported from the plugin. These can be used to setup [custom keybinding](#usage) or to make your own custom comment function. All API functions can take a `{motion}` (Read `:h :map-operator`) and a optional [`{cfg}`](../README.md#config) argument which can be used to override the [default configuration](../README.md#config)
-
-<details>
-<summary>Deprecated API</summary>
-
-```lua
----@alias OpMode 'line'|'char'|'v'|'V' Vim operator-mode motions. Read `:h map-operator`
-```
-
-### Core
-
-These APIs powers the [basic-mappings](../README.md#basic-mappings).
-
-```lua
---######### LINEWISE #########--
-
----Toggle linewise-comment on the current line
----@param cfg? CommentConfig
-require('Comment.api').toggle_current_linewise(cfg)
-
----(Operator-Pending) Toggle linewise-comment on the current line
----@param opmode OpMode
----@param cfg? CommentConfig
-require('Comment.api').toggle_current_linewise_op(opmode, cfg)
-
----(Operator-Pending) Toggle linewise-comment over multiple lines
----@param opmode OpMode
----@param cfg? CommentConfig
-require('Comment.api').toggle_linewise_op(opmode, cfg)
-
----Toggle linewise-comment over multiple lines using `vim.v.count`
----@param cfg? CommentConfig
-require('Comment.api').toggle_linewise_count(cfg)
-
---######### BLOCKWISE #########--
-
----Toggle blockwise comment on the current line
----@param cfg? CommentConfig
-require('Comment.api').toggle_current_blockwise(cfg)
-
----(Operator-Pending) Toggle blockwise comment on the current line
----@param opmode OpMode
----@param cfg? CommentConfig
-require('Comment.api').toggle_current_blockwise_op(opmode, cfg)
-
----(Operator-Pending) Toggle blockwise-comment over multiple lines
----@param opmode OpMode
----@param cfg? CommentConfig
-require('Comment.api').toggle_blockwise_op(opmode, cfg)
-
----Toggle blockwise-comment over multiple lines using `vim.v.count`
----@param cfg? CommentConfig
-require('Comment.api').toggle_blockwise_count(cfg)
-```
-
-### Extra
-
-These APIs powers the [extra-mappings](../README.md#extra-mappings) and also provides the blockwise version.
-
-```lua
---######### LINEWISE #########--
-
----Insert a linewise-comment below
----@param cfg? CommentConfig
-require('Comment.api').insert_linewise_below(cfg)
-
----Insert a linewise-comment above
----@param cfg? CommentConfig
-require('Comment.api').insert_linewise_above(cfg)
-
----Insert a linewise-comment at the end-of-line
----@param cfg? CommentConfig
-require('Comment.api').insert_linewise_eol(cfg)
-
---######### BLOCKWISE #########--
-
----Insert a blockwise-comment below
----@param cfg? CommentConfig
-require('Comment.api').insert_blockwise_below(cfg)
-
----Insert a blockwise-comment above
----@param cfg? CommentConfig
-require('Comment.api').insert_blockwise_above(cfg)
-
----Insert a blockwise-comment at the end-of-line
----@param cfg? CommentConfig
-require('Comment.api').insert_blockwise_eol(cfg)
-```
-
-### Extended
-
-These APIs powers the [extended-mappings](../README.md#extended-mappings).
-
-```lua
---######### LINEWISE #########--
-
----Comment current line using linewise-comment
----@param cfg? CommentConfig
-require('Comment.api').comment_current_linewise(cfg)
-
----(Operator-Pending) Comment current line using linewise-comment
----@param opmode OpMode
----@param cfg? CommentConfig
-require('Comment.api').comment_current_linewise_op(opmode, cfg)
-
----(Operator-Pending) Comment multiple line using linewise-comment
----@param opmode OpMode
----@param cfg? CommentConfig
-require('Comment.api').comment_linewise_op(opmode, cfg)
-
----Uncomment current line using linewise-comment
----@param cfg? CommentConfig
-require('Comment.api').uncomment_current_linewise(cfg)
-
----(Operator-Pending) Uncomment current line using linewise-comment
----@param opmode OpMode
----@param cfg? CommentConfig
-require('Comment.api').uncomment_current_linewise_op(opmode, cfg)
-
----(Operator-Pending) Uncomment multiple line using linewise-comment
----@param opmode OpMode
----@param cfg? CommentConfig
-require('Comment.api').uncomment_linewise_op(opmode, cfg)
-
---######### BLOCKWISE #########--
-
----Comment current line using linewise-comment
----@param cfg? CommentConfig
-require('Comment.api').comment_current_blockwise(cfg)
-
----(Operator-Pending) Comment current line using blockwise-comment
----@param opmode OpMode
----@param cfg? CommentConfig
-require('Comment.api').comment_current_blockwise_op(opmode, cfg)
-
----Uncomment current line using blockwise-comment
----@param cfg? CommentConfig
-require('Comment.api').uncomment_current_blockwise(cfg)
-
----(Operator-Pending) Uncomment current line using blockwise-comment
----@param opmode OpMode
----@param cfg? CommentConfig
-require('Comment.api').uncomment_current_blockwise_op(opmode, cfg)
-```
-
-</details>
-
-### Core
-
-> **NOTE**:
->
-> 1. All API functions are dot-repeatable except `*.count()`
-> 2. For the `*.current()` functions, `{motion}` argument is optional
-> 3. `{cfg}` is optional for all the API functions
-
-```lua
-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').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').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)
-```
-
-### Additional
-
-```lua
----Callback function to provide dot-repeat support
----NOTE: VISUAL mode mapping doesn't support dot-repeat
----@param cb string Name of the API function to call
-require('Comment.api').call(cb)
-```
-
-<a id="usage"></a>
-
-# ⚙️ Usage
-
-Following are some example keybindings using the APIs.
-
-```lua
--- # NORMAL mode
-
--- Linewise toggle current line using C-/
-vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").toggle.linewise.current()<CR>')
--- or with dot-repeat support
--- vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").call("toggle.linewise.current")<CR>g@$')
-
--- Blockwise toggle current line using C-\
-vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").toggle.blockwise.current()<CR>')
--- or with dot-repeat support
--- vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").call("toggle.blockwise.current")<CR>g@$')
-
--- Linewise toggle multiple line using <leader>gc with dot-repeat support
--- Example: <leader>gc3j will comment 4 lines
-vim.keymap.set('n', '<leader>gc', '<CMD>lua require("Comment.api").call("toggle.linewise")<CR>g@')
-
--- Blockwise toggle multiple line using <leader>gc with dot-repeat support
--- Example: <leader>gb3j will comment 4 lines
-vim.keymap.set('n', '<leader>gb', '<CMD>lua require("Comment.api").call("toggle.blockwise")<CR>g@')
-
--- # VISUAL mode
-
--- Linewise toggle using C-/
-vim.keymap.set('x', '<C-_>', '<ESC><CMD>lua require("Comment.api").toggle.linewise(vim.fn.visualmode())<CR>')
-
--- Blockwise toggle using <leader>gb
-vim.keymap.set('x', '<leader>gb', '<ESC><CMD>lua require("Comment.api").toggle.blockwise(vim.fn.visualmode())<CR>')
-```
+`Comment.nvim` now has `:help` docs 🎉. Read `:h comment.api` for the Lua API documentation and usage.

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 🎉. Read `:h comment.plugmap` for the `<Plug>` mappings documentation and usage.