diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 0870cfc5..4aefac4f 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -8,7 +8,7 @@ on:
- master
env:
- PLUGIN_NAME: Comment
+ DOC: doc/Comment.txt
jobs:
docs:
@@ -18,11 +18,12 @@ jobs:
- uses: actions/checkout@v2
- name: Generating help
+ shell: bash
run: |
curl -Lq https://github.com/numToStr/lemmy-help/releases/latest/download/lemmy-help-x86_64-unknown-linux-gnu.tar.gz | tar xz
./lemmy-help -fact \
lua/Comment/{init.lua,config.lua} plugin/Comment.lua \
- lua/Comment/{api.lua,ft.lua,utils.lua,opfunc.lua,extra.lua} > doc/${{env.PLUGIN_NAME}}.txt
+ lua/Comment/{api.lua,ft.lua,utils.lua,opfunc.lua,extra.lua} > ${{env.DOC}}
- name: Commit
uses: stefanzweifel/git-auto-commit-action@v4
diff --git a/README.md b/README.md
index ee54977e..e99e2529 100644
--- a/README.md
+++ b/README.md
@@ -225,36 +225,29 @@ There are two hook methods i.e `pre_hook` and `post_hook` which are called befor
-- `pre_hook` - Called with a `ctx` argument (Read `:h comment.utils.CommentCtx`) before (un)comment. Can optionally return a `commentstring` to be used for (un)commenting. You can use [nvim-ts-context-commentstring](https://github.com/JoosepAlviste/nvim-ts-context-commentstring) to easily comment `tsx/jsx` files.
+- `pre_hook` - Called with a `ctx` argument (Read `:h comment.utils.CommentCtx`) before (un)comment. Can optionally return a `commentstring` to be used for (un)commenting.
```lua
{
pre_hook = function(ctx)
- -- Only calculate commentstring for tsx filetypes
- if vim.bo.filetype == 'typescriptreact' then
- local U = require('Comment.utils')
-
- -- Determine whether to use linewise or blockwise commentstring
- local type = ctx.ctype == U.ctype.linewise and '__default' or '__multiline'
-
- -- Determine the location where to calculate commentstring from
- local location = nil
- if ctx.ctype == U.ctype.blockwise then
- location = require('ts_context_commentstring.utils').get_cursor_location()
- elseif ctx.cmotion == U.cmotion.v or ctx.cmotion == U.cmotion.V then
- location = require('ts_context_commentstring.utils').get_visual_start_location()
- end
-
- return require('ts_context_commentstring.internal').calculate_commentstring({
- key = type,
- location = location,
- })
+ if ctx.range.srow == ctx.range.erow then
+ -- do something with the current line
+ else
+ -- do something with lines range
end
end,
}
```
-> **Note** - `Comment.nvim` already supports [`treesitter`](#treesitter) out-of-the-box except for `tsx/jsx`.
+You can also integrate [nvim-ts-context-commentstring](https://github.com/JoosepAlviste/nvim-ts-context-commentstring#commentnvim) using `pre_hook` to easily comment `tsx/jsx` files.
+
+> **Note** - `Comment.nvim` already supports [`treesitter`](#treesitter) out-of-the-box for all the languages except `tsx/jsx`.
+
+```lua
+{
+ pre_hook = require('ts_context_commentstring.integrations.comment_nvim').create_pre_hook(),
+}
+```
diff --git a/lua/Comment/api.lua b/lua/Comment/api.lua
index 9c99e435..2236c0af 100644
--- a/lua/Comment/api.lua
+++ b/lua/Comment/api.lua
@@ -11,267 +11,7 @@ local Op = require('Comment.opfunc')
local Ex = require('Comment.extra')
local A = vim.api
-local api = {}
-
------------- OLD START ------------
-
-local function D(name, alt)
- vim.deprecate("require('Comment.api')." .. name, "require('Comment.api')." .. alt, '0.7', 'Comment.nvim', false)
-end
-
---====================================
---============ CORE API ==============
---====================================
-
---######### LINEWISE #########--
-
----@private
----@deprecated
----Toggle linewise-comment on the current line
----@param cfg? CommentConfig
-function api.toggle_current_linewise(cfg)
- D('toggle_current_linewise({cfg})', 'toggle.linewise.current(nil, {cfg})')
- api.toggle.linewise.current(nil, cfg)
-end
-
----@private
----@deprecated
----(Operator-Pending) Toggle linewise-comment on the current line
----@param opmode OpMotion
----@param cfg? CommentConfig
-function api.toggle_current_linewise_op(opmode, cfg)
- D('toggle_current_linewise_op({opmode}, {cfg})', 'toggle.linewise.current({opmode}, {cfg})')
- api.toggle.linewise.current(opmode, cfg)
-end
-
----@private
----@deprecated
----(Operator-Pending) Toggle linewise-comment over multiple lines
----@param opmode OpMotion
----@param cfg? CommentConfig
-function api.toggle_linewise_op(opmode, cfg)
- D('toggle_linewise_op({opmode}, {cfg})', 'toggle.linewise({opmode}, {cfg})')
- api.toggle.linewise(opmode, cfg)
-end
-
----@private
----@deprecated
----Toggle linewise-comment over multiple lines using `vim.v.count`
----@param cfg? CommentConfig
-function api.toggle_linewise_count(cfg)
- D('toggle_linewise_count({cfg})', 'toggle.linewise.count(vim.v.count, {cfg})')
- api.toggle.linewise.count(vim.v.count, cfg)
-end
-
---######### BLOCKWISE #########--
-
----@private
----@deprecated
----Toggle blockwise comment on the current line
----@param cfg? CommentConfig
-function api.toggle_current_blockwise(cfg)
- D('toggle_current_blockwise({cfg})', 'toggle.blockwise.current(nil, {cfg})')
- api.toggle.blockwise.current(nil, cfg)
-end
-
----@private
----@deprecated
----(Operator-Pending) Toggle blockwise comment on the current line
----@param opmode OpMotion
----@param cfg? CommentConfig
-function api.toggle_current_blockwise_op(opmode, cfg)
- D('toggle_current_blockwise_op({opmode}, {cfg})', 'toggle.blockwise.current({opmode}, {cfg})')
- api.toggle.blockwise.current(opmode, cfg)
-end
-
----@private
----@deprecated
----(Operator-Pending) Toggle blockwise-comment over multiple lines
----@param opmode OpMotion
----@param cfg? CommentConfig
-function api.toggle_blockwise_op(opmode, cfg)
- D('toggle_blockwise_op({opmode}, {cfg})', 'toggle.blockwise({opmode}, {cfg})')
- api.toggle.blockwise(opmode, cfg)
-end
-
----@private
----@deprecated
----Toggle blockwise-comment over multiple lines using `vim.v.count`
----@param cfg? CommentConfig
-function api.toggle_blockwise_count(cfg)
- D('toggle_blockwise_count({cfg})', 'toggle.blockwise.count(vim.v.count, {cfg})')
- api.toggle.blockwise.count(vim.v.count, cfg)
-end
-
---=====================================
---============ EXTRA API ==============
---=====================================
-
---######### LINEWISE #########--
-
----@private
----@deprecated
----Insert a linewise-comment below
----@param cfg? CommentConfig
-function api.insert_linewise_below(cfg)
- D('insert_linewise_below({cfg})', 'insert.linewise.below({cfg})')
- api.insert.linewise.below(cfg)
-end
-
----@private
----@deprecated
----Insert a linewise-comment above
----@param cfg? CommentConfig
-function api.insert_linewise_above(cfg)
- D('insert_linewise_above({cfg})', 'insert.linewise.above({cfg})')
- api.insert.linewise.above(cfg)
-end
-
----@private
----@deprecated
----Insert a linewise-comment at the end-of-line
----@param cfg? CommentConfig
-function api.insert_linewise_eol(cfg)
- D('insert_linewise_eol({cfg})', 'insert.linewise.eol({cfg})')
- api.insert.linewise.eol(cfg)
-end
-
---######### BLOCKWISE #########--
-
----@private
----@deprecated
----Insert a blockwise-comment below
----@param cfg? CommentConfig
-function api.insert_blockwise_below(cfg)
- D('insert_blockwise_below({cfg})', 'insert.blockwise.below({cfg})')
- api.insert.blockwise.below(cfg)
-end
-
----@private
----@deprecated
----Insert a blockwise-comment above
----@param cfg? CommentConfig
-function api.insert_blockwise_above(cfg)
- D('insert_blockwise_above({cfg})', 'insert.blockwise.above({cfg})')
- api.insert.blockwise.above(cfg)
-end
-
----@private
----@deprecated
----Insert a blockwise-comment at the end-of-line
----@param cfg? CommentConfig
-function api.insert_blockwise_eol(cfg)
- D('insert_blockwise_eol({cfg})', 'insert.blockwise.eol({cfg})')
- api.insert.blockwise.eol(cfg)
-end
-
---========================================
---============ EXTENDED API ==============
---========================================
-
---######### LINEWISE #########--
-
----@private
----@deprecated
----Comment current line using linewise-comment
----@param cfg? CommentConfig
-function api.comment_current_linewise(cfg)
- D('comment_current_linewise({cfg})', 'comment.linewise.current(nil, {cfg})')
- api.comment.linewise.current(nil, cfg)
-end
-
----@private
----@deprecated
----(Operator-Pending) Comment current line using linewise-comment
----@param opmode OpMotion
----@param cfg? CommentConfig
-function api.comment_current_linewise_op(opmode, cfg)
- D('comment_current_linewise_op({opmode}, {cfg})', 'comment.linewise.current({opmode}, {cfg})')
- api.comment.linewise.current(opmode, cfg)
-end
-
----@private
----@deprecated
----(Operator-Pending) Comment multiple line using linewise-comment
----@param opmode OpMotion
----@param cfg? CommentConfig
-function api.comment_linewise_op(opmode, cfg)
- D('comment_linewise_op({opmode}, {cfg})', 'comment.linewise({opmode}, {cfg})')
- api.comment.linewise(opmode, cfg)
-end
-
----@private
----@deprecated
----Uncomment current line using linewise-comment
----@param cfg? CommentConfig
-function api.uncomment_current_linewise(cfg)
- D('uncomment_current_linewise({cfg})', 'uncomment.linewise.current({nil}, {cfg})')
- api.uncomment.linewise.current(nil, cfg)
-end
-
----@private
----@deprecated
----(Operator-Pending) Uncomment current line using linewise-comment
----@param opmode OpMotion
----@param cfg? CommentConfig
-function api.uncomment_current_linewise_op(opmode, cfg)
- D('uncomment_current_linewise_op({opmode}, {cfg})', 'uncomment.linewise.current({opmode}, {cfg})')
- api.uncomment.linewise.current(opmode, cfg)
-end
-
----@private
----@deprecated
----(Operator-Pending) Uncomment multiple line using linewise-comment
----@param opmode OpMotion
----@param cfg? CommentConfig
-function api.uncomment_linewise_op(opmode, cfg)
- D('uncomment_linewise_op({opmode}, {cfg})', 'uncomment.linewise({opmode}, {cfg})')
- api.uncomment.linewise(opmode, cfg)
-end
-
---######### BLOCKWISE #########--
-
----@private
----@deprecated
----Comment current line using linewise-comment
----@param cfg? CommentConfig
-function api.comment_current_blockwise(cfg)
- D('comment_current_blockwise({cfg})', 'comment.blockwise.current(nil, {cfg})')
- api.comment.blockwise.current(nil, cfg)
-end
-
----@private
----@deprecated
----(Operator-Pending) Comment current line using blockwise-comment
----@param opmode OpMotion
----@param cfg? CommentConfig
-function api.comment_current_blockwise_op(opmode, cfg)
- D('comment_current_blockwise_op({opmode}, {cfg})', 'comment.blockwise.current({opmode}, {cfg})')
- api.comment.blockwise.current(opmode, cfg)
-end
-
----@private
----@deprecated
----Uncomment current line using blockwise-comment
----@param cfg? CommentConfig
-function api.uncomment_current_blockwise(cfg)
- D('uncomment_current_blockwise({cfg})', 'uncomment.blockwise.current(nil, {cfg})')
- api.uncomment.blockwise.current(nil, cfg)
-end
-
----@private
----@deprecated
----(Operator-Pending) Uncomment current line using blockwise-comment
----@param opmode OpMotion
----@param cfg? CommentConfig
-function api.uncomment_current_blockwise_op(opmode, cfg)
- D('uncomment_current_blockwise_op({opmode}, {cfg})', 'uncomment.blockwise.current({opmode}, {cfg})')
- api.uncomment.blockwise.current(opmode, cfg)
-end
-
------------- OLD END ------------
-
-local core = {}
+local api, core = {}, {}
function core.__index(that, ctype)
local idxd = {}
@@ -440,12 +180,9 @@ api.insert = setmetatable({}, {
end,
})
--- TODO: After removing old API
--- 1. make `api.locked` a simple function call
--- 2. fix emmylua doc
-
---Wraps the given API function with 'lockmarks' to preserve marks/jumps
----@type fun(cb:string):fun(motion:OpMotion)
+---@param cb string Name of API function
+---@return fun(motion:OpMotion) #Callback function
---@see lockmarks
---@see comment.opfunc.OpMotion
---@usage [[
@@ -468,21 +205,13 @@ api.insert = setmetatable({}, {
--- lockmarks lua require('Comment.api').toggle.linewise.current()
---]])
---@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,
- __call = function(_, cb)
- ---operatorfunc callback
- ---@param motion OpMotion
- return function(motion)
- return A.nvim_command(
- ('lockmarks lua require("Comment.api").%s(%s)'):format(cb, motion and ('%q'):format(motion))
- )
- end
- end,
-})
+function api.locked(cb)
+ return function(motion)
+ return A.nvim_command(
+ ('lockmarks lua require("Comment.api").%s(%s)'):format(cb, motion and ('%q'):format(motion))
+ )
+ end
+end
---Callback function which does the following
--- 1. Sets 'operatorfunc' for dot-repeat
@@ -490,7 +219,7 @@ api.locked = setmetatable({}, {
--- 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
+---@return fun():string #Keymap RHS callback
---@see g@
---@see operatorfunc
---@usage [[
diff --git a/lua/Comment/config.lua b/lua/Comment/config.lua
index 775c8947..2098a956 100644
--- a/lua/Comment/config.lua
+++ b/lua/Comment/config.lua
@@ -34,7 +34,8 @@
---<
---@brief ]]
----@class CommentConfig Plugin's configuration
+---Plugin's configuration
+---@class CommentConfig
---Controls space between the comment
---and the line (default: 'true')
---@field padding boolean|fun():boolean
@@ -63,7 +64,8 @@
---(default: 'nil')
---@field post_hook fun(ctx)
----@class Mappings Create default mappings
+---Create default mappings
+---@class Mappings
---Enables operator-pending mapping; `gcc`, `gbc`,
---`gc{motion}` and `gb{motion}` (default: 'true')
---@field basic boolean
@@ -75,15 +77,18 @@
---(default: 'false')
---@field extended boolean
----@class Toggler LHS of toggle mappings in NORMAL
+---LHS of toggle mappings in NORMAL
+---@class Toggler
---@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
+---LHS of operator-mode mappings in NORMAL and VISUAL mode
+---@class Opleader
---@field line string Linewise comment (default: 'gc')
---@field block string Blockwise comment (default: 'gb')
----@class ExtraMapping LHS of extra mappings
+---LHS of extra mappings
+---@class ExtraMapping
---@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')
diff --git a/lua/Comment/ft.lua b/lua/Comment/ft.lua
index 826b3ab1..8e0ad800 100644
--- a/lua/Comment/ft.lua
+++ b/lua/Comment/ft.lua
@@ -12,7 +12,7 @@
local A = vim.api
----Common commentstring shared b/w mutliple languages
+---Common commentstring shared b/w multiple languages
local M = {
cxx_l = '//%s',
cxx_b = '/*%s*/',
@@ -29,7 +29,7 @@ local M = {
lisp_b = '#|%s|#',
}
----Lang table that contains commentstring (linewise/blockwise) for mutliple filetypes
+---Lang table that contains commentstring (linewise/blockwise) for multiple filetypes
---Structure = { filetype = { linewise, blockwise } }
---@type table
local L = setmetatable({
@@ -163,7 +163,7 @@ end
---@param lang string Filetype/Language of the buffer
---@param ctype? integer See |comment.utils.ctype|. If given `nil`, it'll
---return a copy of { line, block } commentstring.
----@return nil|string|string[] _ Commentstring
+---@return nil|string|string[] #Commentstring
---@usage [[
---local ft = require('Comment.ft')
---local U = require('Comment.utils')
@@ -198,7 +198,7 @@ end
---@param tree userdata Parse tree to be walked
---@param range integer[] Range to check
---{start_row, start_col, end_row, end_col}
----@return userdata _ Returns a |treesitter-languagetree|
+---@return userdata #Returns a |treesitter-languagetree|
---@see treesitter-languagetree
---@see lua-treesitter-core
---@usage [[
@@ -219,7 +219,7 @@ end
---Calculate commentstring with the power of treesitter
---@param ctx CommentCtx
----@return nil|string _ Commentstring
+---@return nil|string #Commentstring
---@see comment.utils.CommentCtx
function ft.calculate(ctx)
local buf = A.nvim_get_current_buf()
diff --git a/lua/Comment/init.lua b/lua/Comment/init.lua
index 54a11462..084bb835 100644
--- a/lua/Comment/init.lua
+++ b/lua/Comment/init.lua
@@ -51,8 +51,8 @@
---@brief ]]
---@tag comment.sourcecode
---@brief [[
----Comment.nvim is FOSS provided under MIT license. All the source code is avaiable
----at https://github.com/numToStr/Comment.nvim
+---Comment.nvim is FOSS and distributed under MIT license. All the source code is
+---available at https://github.com/numToStr/Comment.nvim
---@brief ]]
---@mod comment.usage Usage
@@ -60,14 +60,14 @@
---Before using the plugin, you need to call the `setup()` function to create the
---default mappings. If you want, you can also override the default configuration
---by giving it a partial 'comment.config.Config' object, it will then be merged
----with the default config.
+---with the default configuration.
---@brief ]]
local C = {}
---Configures the plugin
---@param config? CommentConfig User configuration
----@return CommentConfig _ Returns the mutated config
+---@return CommentConfig #Returns the mutated config
---@see comment.config
---@usage [[
----- Use default configuration
diff --git a/lua/Comment/opfunc.lua b/lua/Comment/opfunc.lua
index fecc7a0f..de4426c6 100644
--- a/lua/Comment/opfunc.lua
+++ b/lua/Comment/opfunc.lua
@@ -12,10 +12,10 @@ local Op = {}
---Vim operator-mode motion enum. Read |:map-operator|
---@alias OpMotion
----| 'line' # Vertical motion
----| 'char' # Horizontal motion
----| 'v' # Visual Block motion
----| 'V' # Visual Line motion
+---| '"line"' # Vertical motion
+---| '"char"' # Horizontal motion
+---| '"v"' # Visual Block motion
+---| '"V"' # Visual Line motion
---Common operatorfunc callback
---This function contains the core logic for comment/uncomment
@@ -117,7 +117,8 @@ function Op.count(count, cfg, cmode, ctype)
U.is_fn(cfg.post_hook, ctx)
end
----@class OpFnParams Operator-mode function parameters
+---Operator-mode function parameters
+---@class OpFnParams
---@field cfg CommentConfig
---@field cmode integer See |comment.utils.cmode|
---@field lines string[] List of lines
diff --git a/lua/Comment/utils.lua b/lua/Comment/utils.lua
index c17d8172..cac12459 100644
--- a/lua/Comment/utils.lua
+++ b/lua/Comment/utils.lua
@@ -4,19 +4,22 @@ local A = vim.api
local U = {}
----@class CommentCtx Comment context
+---Comment context
+---@class CommentCtx
---@field ctype integer See |comment.utils.ctype|
---@field cmode integer See |comment.utils.cmode|
---@field cmotion integer See |comment.utils.cmotion|
---@field range CommentRange
----@class CommentRange Range of the selection that needs to be commented
+---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
----@class CommentMode Comment modes - Can be manual or computed via operator-mode
+---Comment modes - Can be manual or computed via operator-mode
+---@class CommentMode
---@field toggle integer Toggle action
---@field comment integer Comment action
---@field uncomment integer Uncomment action
@@ -29,7 +32,8 @@ U.cmode = {
uncomment = 2,
}
----@class CommentType Comment types
+---Comment types
+---@class CommentType
---@field linewise integer Use linewise commentstring
---@field blockwise integer Use blockwise commentstring
@@ -40,7 +44,8 @@ U.ctype = {
blockwise = 2,
}
----@class CommentMotion Comment motion types
+---Comment motion types
+---@class CommentMotion
---@field line integer Line motion (ie. 'gc2j')
---@field char integer Character/left-right motion (ie. 'gc2w')
---@field block integer Visual operator-pending motion
@@ -119,7 +124,7 @@ end
---Get lines from the current position to the given count
---@param count integer Probably 'vim.v.count'
----@return string[] _ List of lines
+---@return string[] #List of lines
---@return CommentRange
function U.get_count_lines(count)
local srow = unpack(A.nvim_win_get_cursor(0))
@@ -131,7 +136,7 @@ end
---Get lines from a NORMAL/VISUAL mode
---@param range CommentRange
----@return string[] _ List of lines
+---@return string[] #List of lines
function U.get_lines(range)
-- If start and end is same, then just return the current line
if range.srow == range.erow then
diff --git a/plugin/Comment.lua b/plugin/Comment.lua
index 9681d9d0..4d780cf7 100644
--- a/plugin/Comment.lua
+++ b/plugin/Comment.lua
@@ -3,9 +3,9 @@ local call = require('Comment.api').call
---@mod comment.keybindings Keybindings
---@brief [[
----Comment.nvim provides default keybinds which is used for (un)comment your code.
----These keybinds are enabled upon calling |commen.usage.setup| and can be
----configured or disabled, if desired.
+---Comment.nvim provides default keybindings for (un)comment your code. These
+---keybinds are enabled upon calling |commen.usage.setup| and can be configured
+---or disabled, if desired.
---
---Basic: ~
---
@@ -38,8 +38,8 @@ local call = require('Comment.api').call
---@mod comment.plugmap Plug Mappings
---@brief [[
---Comment.nvim provides mappings for most commonly used actions. These
----can be used to make custom keybindings and are enabled by default. All plug
----mappings has support for dot-repeat except VISUAL mode keybindings. To create
+---are enabled by default and can be used to make custom keybindings. All plug
+---mappings have support for dot-repeat except VISUAL mode keybindings. To create
---custom comment function, check out 'comment.api' section.
---
--- *(comment_toggle_linewise)*