Added type annotations (to be reviewed)

Author: markelca

lua/clapi/finder.lua

@@ -5,8 +5,15 @@ local make_entry = require("clapi.make_entry")
 local parser = require("clapi.parser.init")
 local async = require("plenary.async")
 
+---@class FinderModule
 local M = {}
 
+---Build and display a telescope picker with module interface
+---@param opts? table Configuration options
+---@param opts.bufnr? integer Buffer number, defaults to current buffer (0)
+---@param opts.path_display? table|string How to display paths
+---@param opts.entry_maker? function Custom entry maker function
+---@return nil
 M.builtin = function(opts)
 	opts = opts or {}
 	opts.bufnr = opts.bufnr or 0

lua/clapi/init.lua

@@ -1,5 +1,7 @@
 local finder = require("clapi.finder")
 
+---@class CLAPI
+---@field builtin fun(opts?: table): nil
 local M = {}
 
 -- TODO: Unit test the whole plugin

lua/clapi/lsp.lua

@@ -1,9 +1,16 @@
 local utils = require("clapi.utils")
 local async = require("plenary.async")
 
+---@class LSPModule
 local M = {}
 
----@param opts table
+---Gets a file path from a position using LSP
+---@param opts table Options for the LSP definition request
+---@param opts.bufnr? integer Buffer number, defaults to current buffer (0)
+---@param opts.position table The position in the buffer {line, character}
+---@param opts.position.line integer Line number (0-indexed)
+---@param opts.position.character integer Character/column position (0-indexed)
+---@return string|nil filepath The file path or nil if not found
 M.get_file_from_position = async.wrap(function(opts, callback)
 	opts = opts or {}
 	opts.bufnr = opts.bufnr or 0
@@ -19,6 +26,8 @@ M.get_file_from_position = async.wrap(function(opts, callback)
 
 	local callback_called = false
 
+	---Safe callback to prevent multiple callbacks
+	---@param result string|nil The file path or nil
 	local function safe_callback(result)
 		if not callback_called then
 			callback_called = true

lua/clapi/make_entry.lua

@@ -5,8 +5,10 @@ local make_entry = require("telescope.make_entry")
 local utils = require("telescope.utils")
 local entry_display = require("telescope.pickers.entry_display")
 
+---@class MakeEntry
 local M = {}
 
+---@type table<string, string>
 local lsp_type_highlight = {
 	["Class"] = "TelescopeResultsClass",
 	["Constant"] = "TelescopeResultsConstant",
@@ -18,8 +20,12 @@ local lsp_type_highlight = {
 	["Variable"] = "TelescopeResultsVariable",
 }
 
+---Get the filename function with caching
+---@return function
 local get_filename_fn = function()
 	local bufnr_name_cache = {}
+	---@param bufnr? integer Buffer number
+	---@return string filename
 	return function(bufnr)
 		bufnr = vim.F.if_nil(bufnr, 0)
 		local c = bufnr_name_cache[bufnr]
@@ -33,6 +39,15 @@ local get_filename_fn = function()
 	end
 end
 
+---Generate an entry function for LSP symbols with visibility
+---@param opts? table Options for customizing entry display
+---@param opts.bufnr? integer Buffer number
+---@param opts.symbol_width? integer Width for symbol columns
+---@param opts.symbol_type_width? integer Width for symbol type column
+---@param opts.fname_width? integer Width for filename column
+---@param opts.show_line? boolean Whether to show the line content
+---@param opts.symbol_highlights? table<string, string> Custom highlights for symbol types
+---@return function entry_maker Function to create entries
 function M.gen_from_lsp_symbols(opts)
 	opts = opts or {}
 
@@ -64,6 +79,9 @@ function M.gen_from_lsp_symbols(opts)
 	})
 	local type_highlight = vim.F.if_nil(opts.symbol_highlights or lsp_type_highlight)
 
+	---Create display for an entry
+	---@param entry table The entry to display
+	---@return string
 	local make_display = function(entry)
 		local msg
 
@@ -96,6 +114,8 @@ function M.gen_from_lsp_symbols(opts)
 	end
 
 	local get_filename = get_filename_fn()
+	---@param entry table Raw entry from finder
+	---@return table Processed entry
 	return function(entry)
 		local filename = vim.F.if_nil(entry.filename, get_filename(entry.bufnr))
 		local symbol_msg = entry.text

lua/clapi/parser/__get_query.lua

@@ -1,7 +1,9 @@
 local utils = require("clapi.utils")
 
----@param lang string
----@param query_group string
+---Get a treesitter query for a specific language and query group
+---@param lang string The language to get the query for
+---@param query_group string The query group name (e.g., "locals", "parent")
+---@return string|nil query The query string or nil if not found
 return function(lang, query_group)
 	-- TODO: nil check
 	local results = vim.api.nvim_get_runtime_file(string.format("queries/%s/%s.scm", lang, query_group), true)

lua/clapi/parser/__parser.lua

@@ -1,40 +1,51 @@
 ---@class Parser
+---@field private __index any
 local Parser = {}
 
+---Create a new parser instance
+---@param o? table Optional initial object
+---@return Parser
 function Parser:new(o)
 	o = o or {}
 	setmetatable(o, self)
 	self.__index = self
 	return o
 end
 
+---Get visibility modifier of a node
 ---@param node TSNode The treesitter node of the visibility modifier
 ---@param bufnr integer The buffer number of the source file
 ---@return string visibility The visibility modifier of the node
 function Parser.get_visibility(node, bufnr)
 	error("Not implemented!")
 end
 
----@param node TSNode
----@param start_col integer
----@param start_row integer
----@param opts table
+---Parse a method node
+---@param node TSNode The treesitter node of the method
+---@param start_col integer Starting column of the node
+---@param start_row integer Starting row of the node
+---@param opts table Additional options
+---@return table Method information
 function Parser.parse_method(node, start_col, start_row, opts)
 	error("Not implemented!")
 end
 
----@param node TSNode
----@param start_col integer
----@param start_row integer
----@param opts table
+---Parse a constant node
+---@param node TSNode The treesitter node of the constant
+---@param start_col integer Starting column of the node
+---@param start_row integer Starting row of the node
+---@param opts table Additional options
+---@return table Constant information
 function Parser.parse_constant(node, start_col, start_row, opts)
 	error("Not implemented!")
 end
 
----@param node TSNode
----@param start_col integer
----@param start_row integer
----@param opts table
+---Parse a property node
+---@param node TSNode The treesitter node of the property
+---@param start_col integer Starting column of the node
+---@param start_row integer Starting row of the node
+---@param opts table Additional options
+---@return table Property information
 function Parser.parse_property(node, start_col, start_row, opts)
 	error("Not implemented!")
 end

lua/clapi/parser/__parser_java.lua

@@ -1,8 +1,10 @@
 local Parser = require("clapi.parser.__parser")
 
+---@class JavaParser : Parser
 local JavaParser = Parser:new()
 
----@param node TSNode The treesitter node of the visibility modifier
+---Extract visibility from Java modifiers
+---@param node TSNode The treesitter node containing modifiers
 ---@param bufnr integer The buffer number of the source file
 ---@return string visibility The visibility modifier of the node
 local function _get_visibility_from_modifiers(node, bufnr)
@@ -21,6 +23,7 @@ local function _get_visibility_from_modifiers(node, bufnr)
 	return "private"
 end
 
+---Get visibility modifier of a node
 ---@param node TSNode The treesitter node of the visibility modifier
 ---@param bufnr integer The buffer number of the source file
 ---@return string visibility The visibility modifier of the node
@@ -34,10 +37,12 @@ function JavaParser.get_visibility(node, bufnr)
 	return "private"
 end
 
----@param node TSNode
----@param start_col integer
----@param start_row integer
----@param opts table
+---Parse a property node
+---@param node TSNode The treesitter node of the property
+---@param start_col integer Starting column of the node
+---@param start_row integer Starting row of the node
+---@param opts table Additional options
+---@return table PropertyInfo Property information
 function JavaParser.parse_property(node, start_col, start_row, opts)
 	local visibility = JavaParser.get_visibility(node:parent():parent(), opts.bufnr)
 	local text = vim.treesitter.get_node_text(node, opts.bufnr)
@@ -51,10 +56,12 @@ function JavaParser.parse_property(node, start_col, start_row, opts)
 	}
 end
 
----@param node TSNode
----@param start_col integer
----@param start_row integer
----@param opts table
+---Parse a method node
+---@param node TSNode The treesitter node of the method
+---@param start_col integer Starting column of the node
+---@param start_row integer Starting row of the node
+---@param opts table Additional options
+---@return table MethodInfo Method information
 function JavaParser.parse_method(node, start_col, start_row, opts)
 	local visibility = JavaParser.get_visibility(node:parent(), opts.bufnr)
 	local text = vim.treesitter.get_node_text(node, opts.bufnr)

lua/clapi/parser/__parser_php.lua

@@ -1,7 +1,9 @@
 local Parser = require("clapi.parser.__parser")
 
+---@class PhpParser : Parser
 local PhpParser = Parser:new()
 
+---Get visibility modifier of a node
 ---@param node TSNode The treesitter node of the visibility modifier
 ---@param bufnr integer The buffer number of the source file
 ---@return string visibility The visibility modifier of the node
@@ -15,10 +17,12 @@ function PhpParser.get_visibility(node, bufnr)
 	return "public" -- Public by default (TODO: review this wih more languages)
 end
 
----@param node TSNode
----@param start_col integer
----@param start_row integer
----@param opts table
+---Parse a method node
+---@param node TSNode The treesitter node of the method
+---@param start_col integer Starting column of the node
+---@param start_row integer Starting row of the node
+---@param opts table Additional options
+---@return table MethodInfo Method information
 function PhpParser.parse_method(node, start_col, start_row, opts)
 	local visibility = PhpParser.get_visibility(node:parent(), opts.bufnr)
 	local text = vim.treesitter.get_node_text(node, opts.bufnr)
@@ -32,10 +36,12 @@ function PhpParser.parse_method(node, start_col, start_row, opts)
 	}
 end
 
----@param node TSNode
----@param start_col integer
----@param start_row integer
----@param opts table
+---Parse a constant node
+---@param node TSNode The treesitter node of the constant
+---@param start_col integer Starting column of the node
+---@param start_row integer Starting row of the node
+---@param opts table Additional options
+---@return table ConstantInfo Constant information
 function PhpParser.parse_constant(node, start_col, start_row, opts)
 	local text = vim.treesitter.get_node_text(node, opts.bufnr)
 	local visibility = PhpParser.get_visibility(node:parent():parent(), opts.bufnr)
@@ -49,10 +55,12 @@ function PhpParser.parse_constant(node, start_col, start_row, opts)
 	}
 end
 
----@param node TSNode
----@param start_col integer
----@param start_row integer
----@param opts table
+---Parse a property node
+---@param node TSNode The treesitter node of the property
+---@param start_col integer Starting column of the node
+---@param start_row integer Starting row of the node
+---@param opts table Additional options
+---@return table PropertyInfo Property information
 function PhpParser.parse_property(node, start_col, start_row, opts)
 	local parent = node:parent()
 	local prop_parent = parent

lua/clapi/parser/init.lua

@@ -4,9 +4,11 @@ local tsparsers = require("nvim-treesitter.parsers")
 local async = require("plenary.async")
 local lsp = require("clapi.lsp")
 
+---@class ParserModule
 local M = {}
 
----@param lang string
+---Get a parser for a specific language
+---@param lang string Language name
 ---@return Parser|nil
 local function get_parser(lang)
 	if not lang then
@@ -17,6 +19,7 @@ local function get_parser(lang)
 		return
 	end
 
+	---@type table<string, Parser>
 	local parsers = {
 		["php"] = require("clapi.parser.__parser_php"),
 		["java"] = require("clapi.parser.__parser_java"),
@@ -34,8 +37,11 @@ local function get_parser(lang)
 
 	return parser:new()
 end
----
----@param opts table
+
+---Get parent class file and parse its definitions
+---@param opts table Options for parsing
+---@param opts.bufnr? integer Buffer number, defaults to current buffer (0)
+---@return table|nil definitions List of definitions from parent class or nil if error
 local get_parent_file = async.wrap(function(opts, callback)
 	opts = opts or {}
 	opts.bufnr = opts.bufnr or 0
@@ -89,7 +95,7 @@ local get_parent_file = async.wrap(function(opts, callback)
 	local result = {}
 
 	async.run(function()
-		for id, node, metadata in query:iter_captures(root, opts.bufnr) do
+		for id, node, _ in query:iter_captures(root, opts.bufnr) do
 			local capture_name = query.captures[id]
 			if capture_name == "parent" then
 				local line, char = node:start()
@@ -114,7 +120,14 @@ local get_parent_file = async.wrap(function(opts, callback)
 	end)
 end, 2)
 
----@param opts table
+---Parse a file for LSP symbols
+---@param opts table Options for parsing
+---@param opts.filename? string Path to the file (cannot be used with bufnr)
+---@param opts.bufnr? integer Buffer number (cannot be used with filename)
+---@param opts.class_name? string Name of the class to filter results
+---@param opts.filetype? string Force filetype instead of detecting from extension
+---@param opts.query_str? string Custom query string instead of loading from queries
+---@return table|nil results List of symbols found or nil if error
 M.parse_file = async.wrap(function(opts, callback)
 	opts = opts or {}
 	opts.class_name = opts.class_name and string.format("%s::", opts.class_name) or ""

lua/clapi/utils.lua

@@ -1,8 +1,12 @@
+---@class Utils
 local utils = {}
 
 --- Clapi Wrapper around vim.notify
----@param funname string: name of the function that will be
----@param opts table: opts.level string, opts.msg string, opts.once bool
+---@param funname string Name of the function that will be logged
+---@param opts table Options for notification
+---@param opts.level string The log level (ERROR, WARN, INFO, DEBUG, TRACE)
+---@param opts.msg string The message to display
+---@param opts.once? boolean Whether to only notify once, defaults to false
 function utils.notify(funname, opts)
 	opts.once = vim.F.if_nil(opts.once, false)
 	local level = vim.log.levels[opts.level]
@@ -15,6 +19,9 @@ function utils.notify(funname, opts)
 	})
 end
 
+---Read file contents from a path
+---@param path string The path to the file
+---@return string|nil content The file content or nil if file doesn't exist
 function utils.read_file(path)
 	-- Check if the file exists
 	if vim.fn.filereadable(path) == 0 then
@@ -29,7 +36,9 @@ function utils.read_file(path)
 	return content
 end
 
----@param filepath string
+---Get the file extension from a filepath
+---@param filepath string The path to the file
+---@return string|nil extension The file extension or nil if not found
 function utils.get_file_extension(filepath)
 	-- Find the last dot position
 	local lastDotIndex = filepath:match("^.+()%.%w+$")