From 62dacd2c04f0ef62539568f4ac446258eb67cb65 Mon Sep 17 00:00:00 2001
From: Fernando Schauenburg <dev@schauenburg.me>
Date: Thu, 1 Aug 2024 22:44:38 +0200
Subject: [PATCH] nvim: add comments to undocumented functions

---
 config/nvim/lua/fschauen/util/autoformat.lua |  2 +-
 config/nvim/lua/fschauen/util/lua.lua        | 12 ++++++++++++
 config/nvim/lua/fschauen/util/options.lua    |  6 ++++++
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/config/nvim/lua/fschauen/util/autoformat.lua b/config/nvim/lua/fschauen/util/autoformat.lua
index 922ebf8..94c502a 100644
--- a/config/nvim/lua/fschauen/util/autoformat.lua
+++ b/config/nvim/lua/fschauen/util/autoformat.lua
@@ -41,7 +41,7 @@ M.toggle = function()
   end
 end
 
----Crate a lualine component that shows an icon when autoformatting is enabled.
+---Create a lualine component that shows an icon when autoformatting is enabled.
 ---@return table component
 M.lualine = function()
   local icon = require("fschauen.util.icons").ui.Format
diff --git a/config/nvim/lua/fschauen/util/lua.lua b/config/nvim/lua/fschauen/util/lua.lua
index 1d6971a..7edfcc2 100644
--- a/config/nvim/lua/fschauen/util/lua.lua
+++ b/config/nvim/lua/fschauen/util/lua.lua
@@ -3,6 +3,10 @@ local M = {}
 local util = require("fschauen.util")
 local exists = util.exists
 
+---Find lua module source.
+---@param modname string Module name.
+---@return table results List of source files in the runtime path that implement
+---                      `modname`.
 local find_module_sources = function(modname)
   modname = modname:gsub("^%.+", ""):gsub("/", ".")
   local base = "lua/" .. modname:gsub("%.", "/")
@@ -18,6 +22,10 @@ local find_module_sources = function(modname)
   return results
 end
 
+---Execute lua script in lines.
+---@param first integer|nil First line to execute. If nil, execute current line.
+---@param last integer|nil Last line to execute. If nil, execute only the first
+---                       line.
 M.execute_lines = function(first, last)
   first = first or vim.fn.line(".")
   last = last or first
@@ -25,6 +33,7 @@ M.execute_lines = function(first, last)
   loadstring(code)()
 end
 
+---Execute current selection as a lua chunk.
 M.execute_selection = function()
   local selection = { vim.fn.line("v"), vim.fn.line(".") }
   table.sort(selection)
@@ -39,6 +48,9 @@ M.execute_file = function(path)
   end
 end
 
+---Edit a lua module.
+---@param modname string|nil Module name. If nil, edit path name under cursor
+---                          (meant to be mapped to `gf`).
 M.go_to_module = function(modname)
   modname = modname or vim.fn.expand("<cfile>")
 
diff --git a/config/nvim/lua/fschauen/util/options.lua b/config/nvim/lua/fschauen/util/options.lua
index 5782b44..445f466 100644
--- a/config/nvim/lua/fschauen/util/options.lua
+++ b/config/nvim/lua/fschauen/util/options.lua
@@ -1,21 +1,27 @@
 local M = {}
 
+---Toggle 'number' and disable 'relativenumber'.
 M.toggle_number = function()
   vim.wo.number = not vim.wo.number
   vim.wo.relativenumber = false
 end
 
+---Toggle 'relativenumber' and enable 'number' if disabled.
 M.toggle_relativenumber = function()
   vim.wo.relativenumber = not vim.wo.relativenumber
   vim.wo.number = vim.wo.relativenumber or vim.wo.number
 end
 
+---Toggle 'list'.
 M.toggle_list = function() vim.wo.list = not vim.wo.list end
 
+---Toggle 'wrap'.
 M.toggle_wrap = function() vim.wo.wrap = not vim.wo.wrap end
 
+---Toggle 'spell'.
 M.toggle_spell = function() vim.wo.spell = not vim.wo.spell end
 
+---Set buffer options for git commits.
 M.set_gitcommit_buffer_options = function()
   vim.bo.textwidth = 72
   vim.opt.formatoptions:append("t") -- wrap text on 'textwidth'