feat(docs): add proper code documentation

Author: rachartier

lua/tiny-code-action/action.lua

@@ -4,10 +4,10 @@ local utils = require("tiny-code-action.utils")
 local apply_edit = require("tiny-code-action.edit").apply_edit
 
 --- Applies a given action in the context of a client and a context.
--- @param action The action to be applied. If nil, an error message is displayed.
--- @param client The client in which the action is applied. It is used to apply workspace edits and execute commands.
--- @param ctx The context in which the action is applied. If not provided, an empty context is used.
--- @return No return value. The function operates by side effects, applying the action in the given context.
+--- @param action The action to be applied. If nil, an error message is displayed.
+--- @param client The client in which the action is applied. It is used to apply workspace edits and execute commands.
+--- @param ctx The context in which the action is applied. If not provided, an empty context is used.
+--- @return No return value. The function operates by side effects, applying the action in the given context.
 function M.apply(action, client, ctx)
   if action == nil then
     vim.notify("Error: No action to apply/action can't be applied", vim.log.levels.ERROR)

lua/tiny-code-action/base/picker.lua

@@ -3,9 +3,9 @@ local M = {}
 local utils = require("tiny-code-action.utils")
 
 --- Helper function to check if a picker dependency is available
--- @param name string: Name of the picker
--- @param module_path string: Path to the module to check
--- @return boolean: True if the dependency is available
+--- @param name string: Name of the picker
+--- @param module_path string: Path to the module to check
+--- @returnboolean: True if the dependency is available
 local function has_dependency(name, module_path)
   local has_module, _ = pcall(require, module_path)
   if not has_module then
@@ -19,7 +19,7 @@ local function has_dependency(name, module_path)
 end
 
 --- Initialize a new picker base
--- @param opts table: Options to configure the picker
+--- @param opts table: Options to configure the picker
 function M.new(opts)
   local picker = {
     -- Common properties that all pickers should have

lua/tiny-code-action/base/previewer.lua

@@ -5,7 +5,7 @@ local terminal = require("tiny-code-action.terminal")
 local utils = require("tiny-code-action.utils")
 
 --- Initialize a new previewer base
--- @param opts table: Options to configure the previewer
+--- @param opts table: Options to configure the previewer
 function M.new(opts)
   local previewer = {
     config = opts or {},

lua/tiny-code-action/edit.lua

@@ -120,12 +120,12 @@ end
 
 --- Applies an empty edit to the given lines.
 -- This function takes a list of lines and the details of an edit, and applies the empty edit to the lines. It handles the case where the start and end lines are the same, and the case where they are different.
--- @param lines table: A table of strings, each representing a line of text. The lines are 1-indexed.
--- @param start_line number: The 1-indexed line number where the edit starts.
--- @param end_line number: The 1-indexed line number where the edit ends.
--- @param start_char number: The 0-indexed character position within the start line where the edit starts.
--- @param end_char number: The 0-indexed character position within the end line where the edit ends.
--- @return table: A table of strings, each representing a line of text after the edit has been applied. The lines are 1-indexed.
+--- @param lines table: A table of strings, each representing a line of text. The lines are 1-indexed.
+--- @param start_line number: The 1-indexed line number where the edit starts.
+--- @param end_line number: The 1-indexed line number where the edit ends.
+--- @param start_char number: The 0-indexed character position within the start line where the edit starts.
+--- @param end_char number: The 0-indexed character position within the end line where the edit ends.
+--- @returntable: A table of strings, each representing a line of text after the edit has been applied. The lines are 1-indexed.
 -- @error This function does not explicitly throw errors, but may propagate errors thrown by called functions.
 local function apply_empty_edit(lines, start_line, end_line, start_char, end_char)
   local first = lines[start_line]
@@ -152,8 +152,8 @@ local function apply_empty_edit(lines, start_line, end_line, start_char, end_cha
 end
 --- Applies a single edit to the given lines.
 -- This function takes a list of lines and an edit, and applies the edit to the lines. If the edit's newText is not empty, it applies a non-empty edit. Otherwise, it applies an empty edit. It ensures that the lines exist up to the end line of the edit.
--- @param lines table: A table of strings, each representing a line of text. The lines are 1-indexed.
--- @param edit table: A table representing the edit to be applied. The edit table should have the following structure:
+--- @param lines table: A table of strings, each representing a line of text. The lines are 1-indexed.
+--- @param edit table: A table representing the edit to be applied. The edit table should have the following structure:
 -- {
 --   range = {
 --     start = { line = <number>, character = <number> },
@@ -162,7 +162,7 @@ end
 --   newText = <string>
 -- }
 -- The range's start and end lines are 0-indexed, and the characters are 0-indexed within their respective lines. The newText is the text to replace the range with.
--- @return table: A table of strings, each representing a line of text after the edit has been applied. The lines are 1-indexed.
+--- @returntable: A table of strings, each representing a line of text after the edit has been applied. The lines are 1-indexed.
 -- @error This function does not explicitly throw errors, but may propagate errors thrown by called functions.
 local function apply_single_edit(lines, edit)
   local start_line, end_line = get_line_start_end(edit)
@@ -185,12 +185,12 @@ end
 -- Otherwise, it constructs a new range from the start and end properties of the edit. If the start offset is present,
 -- it adjusts the line numbers accordingly. It also ensures that the start of the range is before the end.
 --
--- @param edit table: The edit to normalize. It should have either a 'range' property or 'start' and 'end' properties.
+--- @param edit table: The edit to normalize. It should have either a 'range' property or 'start' and 'end' properties.
 -- The 'start' and 'end' properties, if present, should be tables with 'line' and 'character' or 'offset' properties.
 -- The 'line' property is a zero-based line number. The 'character' property is a zero-based character index.
 -- The 'offset' property is a one-based index, which is converted to a zero-based index by subtracting one.
 --
--- @return table: Returns a table representing the normalized range. The table has 'start' and 'end' properties,
+--- @returntable: Returns a table representing the normalized range. The table has 'start' and 'end' properties,
 -- each of which is a table with 'line' and 'character' properties. The 'line' property is a zero-based line number.
 -- The 'character' property is a zero-based character index. If the original range was inverted (i.e., the start was
 -- after the end), the returned range is swapped to ensure that the start is before the end.
@@ -226,8 +226,8 @@ local function normalize_range(edit)
 end
 
 -- This function preprocesses a list of edits. It assigns an index to each edit and normalizes its range.
--- @param edits table: A list of edits. Each edit is a table that should have a 'range' field.
--- @return table: A list of edits with preprocessed 'range' and an additional '_index' field.
+--- @param edits table: A list of edits. Each edit is a table that should have a 'range' field.
+--- @returntable: A list of edits with preprocessed 'range' and an additional '_index' field.
 -- @raise No specific exceptions are raised in this function.
 local function preprocess_edits(edits)
   local index = 0
@@ -240,9 +240,9 @@ local function preprocess_edits(edits)
 end
 --- Applies a series of edits to a given set of lines.
 -- This function preprocesses the edits, sorts them, and then applies each edit to the lines in order.
--- @param lines table: A table of strings, where each string represents a line of text. This is the text that the edits will be applied to.
--- @param edits table: A table of edits to apply. Each edit is a table with fields 'range' and 'newText'. 'range' is a table with fields 'start' and 'end', each of which is a table with fields 'line' and 'character'. 'newText' is the text to replace the range with.
--- @return table: A table of strings, representing the lines of text after all edits have been applied.
+--- @param lines table: A table of strings, where each string represents a line of text. This is the text that the edits will be applied to.
+--- @param edits table: A table of edits to apply. Each edit is a table with fields 'range' and 'newText'. 'range' is a table with fields 'start' and 'end', each of which is a table with fields 'line' and 'character'. 'newText' is the text to replace the range with.
+--- @returntable: A table of strings, representing the lines of text after all edits have been applied.
 -- @error Will throw an error if an edit's range is invalid (e.g., 'start' is after 'end', or the line or character indices are out of bounds).
 function M.apply_edit(lines, edits)
   local processed_edits = preprocess_edits(edits)

lua/tiny-code-action/filters.lua

@@ -40,4 +40,3 @@ function M.filter_code_actions(results, filters)
 end
 
 return M
-

lua/tiny-code-action/finder.lua

@@ -20,6 +20,9 @@ local function get_line_diagnostics(bufnr)
 end
 
 -- Find code actions from all LSP clients
+--- Finds code actions from all LSP clients for the given options and invokes the callback with results.
+--- @param opts table: Options including bufnr, range, and context
+--- @param callback function: Function to call with the results
 function M.code_action_finder(opts, callback)
   local results = {}
   local position_encoding = vim.api.nvim_get_option_value("encoding", { scope = "local" })
@@ -99,6 +102,9 @@ function M.code_action_finder(opts, callback)
 end
 
 -- Sort code actions based on priority with isPreferred at the top
+--- Sorts code actions by priority, placing preferred actions at the top.
+--- @param results table: List of code action results
+--- @returntable: Sorted results
 function M.sort_by_preferred(results)
   if not results or #results == 0 then
     return results

lua/tiny-code-action/highlights.lua

@@ -1,5 +1,7 @@
 local M = {}
 
+--- Sets up highlight groups for code action kinds based on provided signs.
+--- @param signs table: Mapping of kind names to sign definitions
 function M.setup_highlights(signs)
   for kind_name, sign in pairs(signs) do
     vim.api.nvim_set_hl(0, "TinyCodeActionKind" .. kind_name, sign[2])

lua/tiny-code-action/init.lua

@@ -12,6 +12,8 @@ M.picker_config = config.picker_config
 
 --- Get the code actions for the current buffer
 --- @param opts table: The options for the code actions (compatible with vim.lsp.buf.code_action).
+--- Gets and displays code actions for the current buffer, applying filters and using the configured picker.
+--- @param opts table: Options for code actions (compatible with vim.lsp.buf.code_action)
 function M.code_action(opts)
   local bufnr = vim.api.nvim_get_current_buf()
   local finder_opts = {
@@ -107,6 +109,8 @@ local function init_backend(backend_name)
   return require("tiny-code-action.backend." .. backend_name)
 end
 
+--- Sets up the plugin configuration, picker, highlights, and backend.
+--- @param opts table: User configuration options
 function M.setup(opts)
   M.config = vim.tbl_deep_extend("force", {}, M.config, opts or {})
 

lua/tiny-code-action/picker.lua

@@ -2,6 +2,9 @@ local config = require("tiny-code-action.config")
 local M = {}
 
 -- Get a picker module by name, with fallbacks
+--- Retrieves a picker module by name, with fallbacks to defaults if unavailable.
+--- @param picker_name string: Name of the picker module
+--- @returntable|nil: Picker module or nil if not found
 function M.get_picker_module(picker_name)
   if not config.VALID_PICKERS[picker_name] then
     vim.notify(
@@ -15,7 +18,10 @@ function M.get_picker_module(picker_name)
     return picker_module
   end
   if picker_name == "telescope" then
-    vim.notify("Telescope picker is not available. Falling back to vim.ui.select.", vim.log.levels.WARN)
+    vim.notify(
+      "Telescope picker is not available. Falling back to vim.ui.select.",
+      vim.log.levels.WARN
+    )
     return M.get_picker_module("select")
   elseif picker_name == "snacks" then
     vim.notify("Snacks picker is not available. Falling back to telescope.", vim.log.levels.WARN)
@@ -32,6 +38,9 @@ function M.get_picker_module(picker_name)
   end
 end
 
+--- Initializes the specified picker, loading extensions if necessary.
+--- @param picker string|table: Picker name or config table
+--- @returnboolean: True if initialization succeeded
 function M.init_picker(picker)
   local picker_name
   if type(picker) == "table" then
@@ -56,4 +65,3 @@ function M.init_picker(picker)
 end
 
 return M
-

lua/tiny-code-action/pickers/buffer.lua

@@ -8,6 +8,10 @@ local M = BasePicker.new()
 
 local ns = vim.api.nvim_create_namespace("tiny_code_action_buffer")
 
+--- Creates and displays the buffer picker window for code actions.
+--- @param config table: Picker configuration
+--- @param results table: List of code action results
+--- @param bufnr number: Buffer number
 function M.create(config, results, bufnr)
   hotkeys.add_config_keymaps_to_reserved(config)