Skip to content

Commit a3a2ab1

Browse files
numToStrnumToStr
committed
chore: API.md
1 parent 996f4a8 commit a3a2ab1

File tree

5 files changed

+55
-26
lines changed

5 files changed

+55
-26
lines changed

‎doc/API.md‎

Lines changed: 48 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# ⚙️ API
22

3-
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 `opmode` (defined below) and a optional [`cfg`](../README.md#config) argument which can be used to override the [default configuration](../README.md#config)
3+
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)
4+
5+
<details>
6+
<summary>Deprecated API</summary>
47

58
```lua
69
---@alias OpMode 'line'|'char'|'v'|'V' Vim operator-mode motions. Read `:h map-operator`
@@ -142,6 +145,42 @@ require('Comment.api').uncomment_current_blockwise(cfg)
142145
require('Comment.api').uncomment_current_blockwise_op(opmode, cfg)
143146
```
144147

148+
</details>
149+
150+
### Core
151+
152+
> **NOTE**:
153+
>
154+
> 1. All API functions are dot-repeatable except `*.count()`
155+
> 2. For the `*.current()` functions, `{motion}` argument is optional
156+
> 3. `{cfg}` is optional for all the API functions
157+
158+
```lua
159+
require('Comment.api').toggle.linewise(motion, cfg)
160+
require('Comment.api').toggle.linewise.current(motion, cfg)
161+
require('Comment.api').toggle.linewise.count(count, cfg)
162+
163+
require('Comment.api').toggle.blockwise(motion, cfg)
164+
require('Comment.api').toggle.blockwise.current(motion, cfg)
165+
require('Comment.api').toggle.blockwise.count(count, cfg)
166+
167+
require('Comment.api').comment.linewise(motion, cfg)
168+
require('Comment.api').comment.linewise.current(motion, cfg)
169+
require('Comment.api').comment.linewise.count(count, cfg)
170+
171+
require('Comment.api').comment.blockwise(motion, cfg)
172+
require('Comment.api').comment.blockwise.current(motion, cfg)
173+
require('Comment.api').comment.blockwise.count(count, cfg)
174+
175+
require('Comment.api').uncomment.linewise(motion, cfg)
176+
require('Comment.api').uncomment.linewise.current(motion, cfg)
177+
require('Comment.api').uncomment.linewise.count(count, cfg)
178+
179+
require('Comment.api').uncomment.blockwise(motion, cfg)
180+
require('Comment.api').uncomment.blockwise.current(motion, cfg)
181+
require('Comment.api').uncomment.blockwise.count(count, cfg)
182+
```
183+
145184
### Additional
146185

147186
```lua
@@ -161,28 +200,28 @@ Following are some example keybindings using the APIs.
161200
-- # NORMAL mode
162201

163202
-- Linewise toggle current line using C-/
164-
vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").toggle_current_linewise()<CR>')
203+
vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").toggle.linewise.current()<CR>')
165204
-- or with dot-repeat support
166-
-- vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").call("toggle_current_linewise_op")<CR>g@$')
205+
-- vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").call("toggle.linewise.current")<CR>g@$')
167206

168207
-- Blockwise toggle current line using C-\
169-
vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").toggle_current_blockwise()<CR>')
208+
vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").toggle.blockwise.current()<CR>')
170209
-- or with dot-repeat support
171-
-- vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").call("toggle_current_blockwise_op")<CR>g@$')
210+
-- vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").call("toggle.blockwise.current")<CR>g@$')
172211

173212
-- Linewise toggle multiple line using <leader>gc with dot-repeat support
174213
-- Example: <leader>gc3j will comment 4 lines
175-
vim.keymap.set('n', '<leader>gc', '<CMD>lua require("Comment.api").call("toggle_linewise_op")<CR>g@')
214+
vim.keymap.set('n', '<leader>gc', '<CMD>lua require("Comment.api").call("toggle.linewise")<CR>g@')
176215

177216
-- Blockwise toggle multiple line using <leader>gc with dot-repeat support
178217
-- Example: <leader>gb3j will comment 4 lines
179-
vim.keymap.set('n', '<leader>gb', '<CMD>lua require("Comment.api").call("toggle_blockwise_op")<CR>g@')
218+
vim.keymap.set('n', '<leader>gb', '<CMD>lua require("Comment.api").call("toggle.blockwise")<CR>g@')
180219

181220
-- # VISUAL mode
182221

183222
-- Linewise toggle using C-/
184-
vim.keymap.set('x', '<C-_>', '<ESC><CMD>lua require("Comment.api").toggle_linewise_op(vim.fn.visualmode())<CR>')
223+
vim.keymap.set('x', '<C-_>', '<ESC><CMD>lua require("Comment.api").toggle.linewise(vim.fn.visualmode())<CR>')
185224

186225
-- Blockwise toggle using <leader>gb
187-
vim.keymap.set('x', '<leader>gb', '<ESC><CMD>lua require("Comment.api").toggle_blockwise_op(vim.fn.visualmode())<CR>')
226+
vim.keymap.set('x', '<leader>gb', '<ESC><CMD>lua require("Comment.api").toggle.blockwise(vim.fn.visualmode())<CR>')
188227
```

‎lua/Comment/api.lua‎

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -266,16 +266,6 @@ end
266266

267267
------------ OLD END ------------
268268

269-
-- TODO:
270-
-- [x] add extra API as `insert.{above,below,eol}`
271-
-- [x] add `count_repeat` but make it private
272-
-- [x] play nice w/ `locked`
273-
-- [x] replace all <Plug>
274-
-- [x] depreact old APIs
275-
-- [x] rename U.ctype.{line => linewise, block => blockwise}
276-
-- [x] move this to api.lua
277-
-- [ ] do something about the API.md
278-
279269
local core = {}
280270
local extra = {}
281271

@@ -412,7 +402,7 @@ api.locked = setmetatable({}, {
412402
---@usage `require('Comment.api').call('toggle.linewise')`
413403
function api.call(cb)
414404
A.nvim_set_option('operatorfunc', ("v:lua.require'Comment.api'.locked'%s'"):format(cb))
415-
Config.position = Config:get().sticky and A.nvim_win_get_cursor(0)
405+
Config.position = Config:get().sticky and A.nvim_win_get_cursor(0) or nil
416406
Config.count = vim.v.count
417407
end
418408

‎lua/Comment/config.lua‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@
4444
---@private
4545
---@class RootConfig
4646
---@field config CommentConfig
47-
---@field position integer[] To be used to restore cursor position
47+
---@field position? integer[] To be used to restore cursor position
4848
---@field count integer Helps with dot-repeat support for count prefix
4949
local Config = {
5050
state = {},

‎lua/Comment/ft.lua‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ local M = {
77
cxx_l = '//%s',
88
cxx_b = '/*%s*/',
99
hash = '#%s',
10-
double_hash = '##%s',
10+
dbl_hash = '##%s',
1111
dash = '--%s',
1212
dash_bracket = '--[[%s]]',
1313
haskell_b = '{-%s-}',
@@ -65,7 +65,7 @@ local L = {
6565
lua = { M.dash, M.dash_bracket },
6666
markdown = { M.html, M.html },
6767
make = { M.hash },
68-
mbsyncrc = { M.double_hash },
68+
mbsyncrc = { M.dbl_hash },
6969
meson = { M.hash },
7070
nix = { M.hash, M.cxx_b },
7171
ocaml = { M.fsharp_b, M.fsharp_b },
@@ -89,7 +89,7 @@ local L = {
8989
teal = { M.dash, M.dash_bracket },
9090
terraform = { M.hash, M.cxx_b },
9191
tex = { M.latex },
92-
template = { M.double_hash },
92+
template = { M.dbl_hash },
9393
tmux = { M.hash },
9494
toml = { M.hash },
9595
typescript = { M.cxx_l, M.cxx_b },
@@ -110,7 +110,7 @@ local ft = {}
110110
---@param lang CommentLang
111111
---@param val string|string[]
112112
function ft.set(lang, val)
113-
L[lang] = type(val) == 'string' and { val } or val
113+
L[lang] = type(val) == 'string' and { val } or val --[[ @as string[] ]]
114114
return ft
115115
end
116116

‎lua/Comment/utils.lua‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -260,7 +260,7 @@ function U.uncommenter(left, right, padding, scol, ecol)
260260
local ll = U.is_empty(left) and left or vim.pesc(left) .. pp
261261
local rr = U.is_empty(right) and right or pp .. vim.pesc(right)
262262
local is_lw = not (scol and scol)
263-
local pattern = is_lw and '^(%s*)' .. ll .. '(.-)' .. rr .. '$'
263+
local pattern = is_lw and '^(%s*)' .. ll .. '(.-)' .. rr .. '$' or ''
264264

265265
return function(line)
266266
-------------------

0 commit comments

Comments
 (0)