feat: help docs :h comment-nvim

Author: numToStr

README.md

@@ -6,7 +6,7 @@
 ### ✨ Features
 
 - Supports treesitter. [Read more](#treesitter)
-- Supports `commentstring`. [Read more](#commentstring)
+- Supports `commentstring`. Read `:h comment.commentstring`
 - Supports line (`//`) and block (`/* */`) comments
 - Dot (`.`) repeat support for `gcc`, `gbc` and friends
 - Count support for `[count]gcc` and `[count]gbc`
@@ -63,7 +63,7 @@ EOF
 
 #### Configuration (optional)
 
-Following are the **default** config for the [`setup()`](#setup). If you want to override, just modify the option that you want then it will be merged with the default config.
+Following are the **default** config for the [`setup()`](#setup). If you want to override, just modify the option that you want then it will be merged with the default config. Read `:h comment.config` for more info.
 
 ```lua
 {
@@ -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
 {
@@ -356,11 +356,11 @@ vim.bo.commentstring = '//%s'
 vim.api.nvim_command('set commentstring=//%s')
 ```
 
-> Run `:h commentstring` for more help
+> Read `:h commentstring` for more help
 
 <a id="ft-lua"></a>
 
-2. You can also use this plugin interface to store both line and block commentstring for the filetype. You can treat this as a more powerful version of the `commentstring`
+2. You can also use this plugin interface to store both line and block commentstring for the filetype. You can treat this as a more powerful version of the `commentstring`. Read `:h comment.ft` for more info.
 
 ```lua
 local ft = require('Comment.ft')
@@ -391,56 +391,6 @@ ft.lang('javascript') -- { '//%s', '/*%s*/' }
 
 > PR(s) are welcome to add more commentstring inside the plugin
 
-<a id="commentstring"></a>
-
-### 🧵 Comment String
-
-Although, `Comment.nvim` supports neovim's `commentstring` but unfortunately it has the least priority. The commentstring is taken from the following place in the respective order.
-
-- [`pre_hook`](#hooks) - If a string is returned from this method then it will be used for commenting.
-
-- [`ft.lua`](#ft-lua) - If the current filetype is found in the table, then the string there will be used.
-
-- `commentstring` - Neovim's native commentstring for the filetype
-
-<a id="commentstring-caveat"></a>
-
-> 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.