refactor(nvim): add luadoc annotations to nvim files

Author: kutsan

home/dot_config/exact_nvim/exact_ftplugin/qf.lua

@@ -4,6 +4,7 @@ local g = vim.g
 -- Disable built-in statusline.
 g.qf_disable_statusline = true
 
+---@type string[]
 local qf_statusline = {
 	'%{repeat(nr2char(32),4)}', -- Generate space characters given number of times.
 	'', -- Show a custom list icon.

home/dot_config/exact_nvim/exact_lsp/lua_ls.lua

@@ -5,7 +5,9 @@ local LspConfig = {
 	},
 	on_init = function(client)
 		if client.workspace_folders then
+			---@type string
 			local path = client.workspace_folders[1].name
+
 			if
 				path ~= vim.fn.stdpath('config')
 				and (

home/dot_config/exact_nvim/exact_lua/exact_user/buffer.lua

@@ -2,7 +2,10 @@ local api = vim.api
 local fn = vim.fn
 local cmd = vim.cmd
 
+---@param opts { force: boolean? }
+---@return false?
 local function remove(opts)
+	---@type integer
 	local target_buf_id = api.nvim_get_current_buf()
 
 	-- Do nothing if buffer is in modified state.
@@ -11,13 +14,16 @@ local function remove(opts)
 	end
 
 	-- Hide target buffer from all windows.
-	vim.tbl_map(function(win_id)
-		win_id = win_id or 0
+	---@type integer[]
+	local win_ids = fn.win_findbuf(target_buf_id)
 
+	for _, win_id in ipairs(win_ids) do
+		---@type integer
 		local current_buf_id = api.nvim_win_get_buf(win_id)
 
 		api.nvim_win_call(win_id, function()
 			-- Try using alternate buffer
+			---@type integer
 			local alt_buf_id = fn.bufnr('#')
 			if alt_buf_id ~= current_buf_id and fn.buflisted(alt_buf_id) == 1 then
 				api.nvim_win_set_buf(win_id, alt_buf_id)
@@ -31,12 +37,11 @@ local function remove(opts)
 			end
 
 			-- Create new listed scratch buffer
+			---@type integer
 			local new_buf = api.nvim_create_buf(true, true)
 			api.nvim_win_set_buf(win_id, new_buf)
 		end)
-
-		return true
-	end, fn.win_findbuf(target_buf_id))
+	end
 
 	cmd.bdelete({ target_buf_id, bang = opts.force })
 end

home/dot_config/exact_nvim/exact_lua/exact_user/foldtext.lua

@@ -1,3 +1,4 @@
+---@return string
 local function foldtext()
 	local start_line = vim.fn.getline(vim.v.foldstart)
 	local end_line = vim.fn.getline(vim.v.foldend)

home/dot_config/exact_nvim/exact_lua/exact_user/shada.lua

@@ -1,7 +1,11 @@
 local function set_shada_file()
+	---@type string?
 	local git_root = require('snacks').git.get_root()
+
+	---@type string
 	local dir = git_root ~= nil and git_root or vim.fn.getcwd()
 
+	---@type string
 	local shada_file = vim.fs.joinpath(
 		vim.fn.stdpath('state'),
 		'shada',

home/dot_config/exact_nvim/exact_lua/exact_user/utils.lua

@@ -1,5 +1,6 @@
 local b = vim.b
 
+---@param cmd string
 local function set_undo_ftplugin(cmd)
 	local undo_cmd = cmd
 

home/dot_config/exact_nvim/exact_plugin/exact_autocmds/buffers.lua

@@ -28,6 +28,7 @@ vim.api.nvim_create_autocmd('BufReadPost', {
 	desc = 'Restore cursor to file position in previous editing session.',
 	pattern = '?*',
 	group = vim.api.nvim_create_augroup('JumpLastPosition', { clear = true }),
+	---@param args { buf: integer }
 	callback = function(args)
 		-- Skip if the buffer is not a normal file or a git commit.
 		if
@@ -37,7 +38,9 @@ vim.api.nvim_create_autocmd('BufReadPost', {
 			return
 		end
 
+		---@type integer[]
 		local mark = vim.api.nvim_buf_get_mark(args.buf, '"')
+		---@type integer
 		local line_count = vim.api.nvim_buf_line_count(args.buf)
 
 		if mark[1] > 0 and mark[1] <= line_count then
@@ -57,6 +60,7 @@ vim.api.nvim_create_autocmd('BufEnter', {
 })
 
 -- Disable persistent undo for sensitive files
+---@type string[]
 local sensitive_patterns = {
 	-- Temp directories
 	'/tmp/*',

home/dot_config/exact_nvim/exact_plugin/exact_autocmds/macro.lua

@@ -1,12 +1,18 @@
 local api = vim.api
+
+---@type integer?
 local win_id = nil
+
+---@type integer?
 local buf_id = nil
 
+---@type { row: integer, col_offset: integer }
 local config = {
 	row = 2,
 	col_offset = 4,
 }
 
+---@return nil
 local function close_banner()
 	if win_id and api.nvim_win_is_valid(win_id) then
 		api.nvim_win_close(win_id, true)
@@ -20,6 +26,7 @@ local function close_banner()
 	buf_id = nil
 end
 
+---@return nil
 local function open_banner()
 	local reg = vim.fn.reg_recording()
 

home/dot_config/exact_nvim/exact_plugin/lsp.lua

@@ -1,8 +1,10 @@
+---@type integer
 local lsp_group = vim.api.nvim_create_augroup('UserLspConfig', { clear = true })
 
 -- Highlight references to the symbol under the cursor.
 vim.api.nvim_create_autocmd('LspAttach', {
 	group = lsp_group,
+	---@param args { buf: integer, data: { client_id: integer } }
 	callback = function(args)
 		local client = vim.lsp.get_client_by_id(args.data.client_id)
 		if not client then
@@ -15,6 +17,7 @@ vim.api.nvim_create_autocmd('LspAttach', {
 				args.buf
 			)
 		then
+			---@type integer
 			local highlight_group =
 				vim.api.nvim_create_augroup('LspDocumentHighlight', { clear = false })
 
@@ -39,14 +42,18 @@ vim.api.nvim_create_autocmd('LspAttach', {
 -- General keymaps for LSP functions.
 vim.api.nvim_create_autocmd('LspAttach', {
 	group = lsp_group,
+	---@param args { buf: integer }
 	callback = function(args)
+		---@type { buffer: integer, silent: boolean }
 		local map_opts = { buffer = args.buf, silent = true }
 
 		vim.keymap.set('n', 'gd', vim.lsp.buf.definition, map_opts)
 		vim.keymap.set('n', 'gD', vim.lsp.buf.declaration, map_opts)
 		vim.keymap.set('n', 'J', vim.diagnostic.open_float, map_opts)
 		vim.keymap.set('n', 'K', function()
+			---@type integer
 			local width = math.floor(vim.o.columns * 0.8)
+			---@type integer
 			local height = math.floor(vim.o.lines * 0.3)
 			vim.lsp.buf.hover({ max_height = height, max_width = width })
 		end, map_opts)
@@ -56,6 +63,7 @@ vim.api.nvim_create_autocmd('LspAttach', {
 -- Keymaps for inlay hints.
 vim.api.nvim_create_autocmd('LspAttach', {
 	group = lsp_group,
+	---@param args { buf: integer, data: { client_id: integer } }
 	callback = function(args)
 		local client = vim.lsp.get_client_by_id(args.data.client_id)
 		if not client then