From 73187657f3f0e7cb408b61438b93d9dc50263ebb Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Sat, 31 Aug 2024 02:58:16 -0400
Subject: [PATCH] docs: add detailed function annotations with return types

---
 lua/data/func.lua | 143 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 106 insertions(+), 37 deletions(-)

diff --git a/lua/data/func.lua b/lua/data/func.lua
index 20cf2e5..f41b1d1 100644
--- a/lua/data/func.lua
+++ b/lua/data/func.lua
@@ -2,18 +2,19 @@
 --          │                    Utility Functions                    │
 --          ╰─────────────────────────────────────────────────────────╯
 
+-- Define a namespace for utility functions
 local M = {}
 
-local bit = require("bit")
-
--- Check if the terminal is kitty
+--- Check if the terminal is kitty
+---@return boolean condition true if the terminal is kitty, false otherwise
 function M.is_kitty()
   local term = os.getenv("TERM") or ""
   local kit = string.find(term, "kitty")
   return kit ~= nil
 end
 
--- Check if using kitty-scrollback
+--- Check if using kitty-scrollback
+---@return boolean condition true if using kitty-scrollback, false otherwise
 function M.is_kitty_scrollback()
   if vim.env.KITTY_SCROLLBACK_NVIM == "true" then
     return true
@@ -21,14 +22,16 @@ function M.is_kitty_scrollback()
   return false
 end
 
--- Check if the terminal is alacritty
+--- Check if the terminal is alacritty
+---@return boolean condition true if the terminal is alacritty, false otherwise
 function M.is_alacritty()
   local term = os.getenv("TERM") or ""
   local alc = string.find(term, "alacritty")
   return alc ~= nil
 end
 
--- Check if the terminal is tmux
+--- Check if the terminal is tmux
+---@return boolean condition true if the terminal is tmux, false otherwise
 function M.is_tmux()
   local tterm = os.getenv("TERM")
   if tterm and string.find(tterm, "screen") then
@@ -43,7 +46,8 @@ function M.is_tmux()
   return false
 end
 
--- Check if the terminal is wezterm
+--- Check if the terminal is wezterm
+---@return boolean condition true if the terminal is wezterm, false otherwise
 function M.is_wezterm()
   local wterm = os.getenv("TERM_PROGRAM")
   if wterm and string.find(wterm, "WezTerm") then
@@ -52,7 +56,8 @@ function M.is_wezterm()
   return false
 end
 
--- Check if the terminal is neovide
+--- Check if the terminal is neovide
+---@return boolean condition true if the terminal is neovide, false otherwise
 function M.is_neovide()
   local neovide = vim.g.neovide
   if neovide then
@@ -61,13 +66,18 @@ function M.is_neovide()
   return false
 end
 
--- Check if the terminal is ssh
+--- Check if the terminal is ssh
+---@return boolean condition true if the terminal is ssh, false otherwise
 function M.is_ssh()
   local ssh = os.getenv("SSH_TTY") or false
-  return ssh
+  if ssh then
+    return true
+  end
+  return false
 end
 
--- Check if OS is Windows
+--- Check if OS is Windows
+---@return boolean condition true if the OS is Windows, false otherwise
 function M.is_windows()
   local win = vim.fn.has("win32") == 1 or vim.fn.has("win64") == 1
   if win then
@@ -76,7 +86,8 @@ function M.is_windows()
   return false
 end
 
--- Check if OS is macOS
+--- Check if OS is macOS
+---@return boolean condition true if the OS is macOS, false otherwise
 function M.is_mac()
   local mac = vim.fn.has("macunix")
   if mac == 1 then
@@ -85,7 +96,8 @@ function M.is_mac()
   return false
 end
 
--- Check if OS is Linux
+--- Check if OS is Linux
+---@return boolean condition true if the OS is Linux, false otherwise
 function M.is_linux()
   local lin = vim.fn.has("unix")
   if lin == 1 then
@@ -94,7 +106,8 @@ function M.is_linux()
   return false
 end
 
--- Return the name of the OS
+--- Get the name of the OS
+---@return string os The name of the OS
 function M.get_os()
   --- @diagnostic disable-next-line: undefined-field
   local os_name = vim.loop.os_uname().sysname
@@ -141,10 +154,16 @@ function M.get_os()
   end
 end
 
--- Function to send a notification
+--- Function to send a notification
+---@param message string The message to send
+---@param level string The level of the notification (default: "info")
+---@return boolean condition true if the notification was sent successfully, false otherwise
 function M.notify(message, level)
   level = level or "info"
   vim.notify(message, vim.log.levels[level:upper()])
+  return true
+end
+
 --- Function to reload all plugins.
 --- @return nil
 function M.reload_all_plugins()
@@ -162,7 +181,9 @@ function M.reload_all_plugins()
   end
 end
 
--- Check if plugin is installed
+--- Check if a plugin is installed.
+---@param plugin string The name of the plugin module to check.
+---@return boolean condition true if the plugin is installed, false otherwise.
 function M.is_installed(plugin)
   -- Check for lazy.nvim
   local lazy_installed = pcall(require, "lazy")
@@ -183,7 +204,16 @@ function M.is_installed(plugin)
   return false
 end
 
--- Helper function to add keymaps with common properties
+--- Condition function to check filetype is not in list
+---@param disabled_filetypes string[] The list of filetypes to check
+---@return boolean|function true if filetype is not in list, false otherwise
+function M.disable_on_filetypes(disabled_filetypes)
+  return function()
+    local filetype = vim.bo.filetype
+    return not vim.tbl_contains(disabled_filetypes, filetype)
+  end
+end
+
 --- Helper function to add keymaps with common properties
 ---@param lhs string|table The keybind (or list of keybinds)
 ---@param rhs string|function The function to execute when the key is pressed
@@ -267,7 +297,10 @@ function M.add_keymap(lhs, rhs, desc, mode, icon, group)
   end
 end
 
--- Helper function to remove keymaps
+--- Helper function to remove keymaps
+---@param lhs string The keybind
+---@param mode string|nil The mode in which the keybind should be removed
+---@return boolean condition true if the keymap was removed, false otherwise
 function M.rm_keymap(lhs, mode)
   mode = mode or "n" -- Default to "n" (normal mode) if mode is not provided
   -- Get all keymaps for the specified mode
@@ -284,14 +317,20 @@ function M.rm_keymap(lhs, mode)
   return false -- Indicate that the keymap did not exist
 end
 
--- Helper function to add a mark
+--- Helper function to add a mark
+---@param mark string The mark to add
+---@param line integer The line to add the mark to
+---@param col integer The column to add the mark to
+---@return boolean condition true if the mark was added, false otherwise
 function M.add_mark(mark, line, col)
   -- Set the mark at the specified line and column
   vim.api.nvim_buf_set_mark(0, mark, line, col, {})
   return true -- Indicate that the mark was successfully added
 end
 
--- Helper function to remove a mark if it exists
+--- Helper function to remove a mark
+---@param mark string The mark to remove
+---@return boolean condition true if the mark was removed, false otherwise
 function M.rm_mark(mark)
   -- Get a list of marks in the current buffer
   local marks = vim.fn.getmarklist(vim.fn.bufnr("%"))
@@ -306,22 +345,27 @@ function M.rm_mark(mark)
   return false -- Indicate that the mark did not exist
 end
 
--- Function to check if buffer is modified
+--- Function to check if buffer is modified
+---@return boolean condition true if buffer is modified, false otherwise
 function M.is_buffer_modified()
   return vim.bo.modified
 end
 
--- Function to check if buffer is empty
+--- Function to check if buffer is empty
+---@return boolean condition true if buffer is empty, false otherwise
 function M.is_buffer_empty()
   return vim.fn.empty(vim.fn.expand("%:t")) == 1
 end
 
--- Function to check if buffer is read-only
+--- Function to check if buffer is read-only
+---@return boolean condition true if buffer is read-only, false otherwise
 function M.is_buffer_readonly()
   return vim.bo.readonly
 end
 
--- Function to check if file exists
+--- Function to check if file exists
+---@param filepath string The path to the file
+---@return boolean condition true if file exists, false otherwise
 function M.file_exists(filepath)
   local f = io.open(filepath, "r")
   if f then
@@ -330,7 +374,8 @@ function M.file_exists(filepath)
   return f ~= nil
 end
 
--- Function to get the current git branch
+--- Function to get the current git branch
+---@return string branch git branch name or "No branch"
 function M.get_git_branch()
   local branch = vim.fn.systemlist("git rev-parse --abbrev-ref HEAD")[1]
   if branch and branch ~= "" then
@@ -340,7 +385,8 @@ function M.get_git_branch()
   end
 end
 
--- Function to get the current git commit hash
+--- Function to get the current git commit hash
+---@return string The current git commit hash or "No commit hash"
 function M.get_git_commit_hash()
   local commit_hash = vim.fn.systemlist("git rev-parse --short HEAD")[1]
   if commit_hash and commit_hash ~= "" then
@@ -350,7 +396,9 @@ function M.get_git_commit_hash()
   end
 end
 
--- Function to execute a shell command
+--- Function to run a shell command
+---@param cmd string The command to run
+---@return string|nil result The output of the command
 function M.run_shell_command(cmd)
   local handle = io.popen(cmd)
   if handle then
@@ -364,7 +412,9 @@ function M.run_shell_command(cmd)
   end
 end
 
--- Get Workspace dimensions with optional output format
+--- Function to get the dimensions of the current window
+---@param format string The format of the dimensions
+---@return string|table dimensions dimensions of the current window
 function M.get_ws_dimensions(format)
   format = format or "verbose"
   local dimensions = {
@@ -387,30 +437,39 @@ function M.get_ws_dimensions(format)
   end
 end
 
--- Function to get the current cursor position
+--- Function to get the cursor position
+---@return integer row The current line number
+---@return integer col The current column number
 function M.get_cursor_position()
   local row, col = unpack(vim.api.nvim_win_get_cursor(0))
   return row, col
 end
 
--- Function to split strings
+--- Function to split a string
+---@param inputstr string The string to split
+---@param sep string The separator
+---@return table output The split string
 function M.split_string(inputstr, sep)
   if sep == nil then
     sep = "%s"
   end
-  local t = {}
+  local output = {}
   for str in string.gmatch(inputstr, "([^" .. sep .. "]+)") do
-    table.insert(t, str)
+    table.insert(output, str)
   end
-  return t
+  return output
 end
 
--- Function to convert RGB to hexadecimal
+--- Function to convert RGB to hexadecimal
+---@param rgb table The RGB color
+---@return string hex The hexadecimal color
 function M.rgb_to_hex(rgb)
   return string.format("#%02x%02x%02x", rgb[1], rgb[2], rgb[3])
 end
 
--- Function to get the foreground color of a highlight group
+--- Function to get the foreground color of a highlight group
+---@param hlgroup string The name of the highlight group
+---@return string|nil hex The foreground color of the highlight group
 function M.get_fg_color(hlgroup)
   local hl = vim.api.nvim_get_hl(0, { name = hlgroup, link = false })
   local fg = hl.fg
@@ -424,7 +483,9 @@ function M.get_fg_color(hlgroup)
   return nil
 end
 
--- Function to get the background color of a highlight group
+--- Function to get the background color of a highlight group
+---@param hlgroup string The name of the highlight group
+---@return string|nil hex The background color of the highlight group
 function M.get_bg_color(hlgroup)
   local hl = vim.api.nvim_get_hl(0, { name = hlgroup, link = false })
   local bg = hl.bg
@@ -438,7 +499,9 @@ function M.get_bg_color(hlgroup)
   return nil
 end
 
--- Function to check the window width for lualine
+--- Function to check if the window is wide enough
+---@param width_limit number The minimum width of the window
+---@return boolean condition true if the window is wide enough, false otherwise
 function M.is_window_wide_enough(width_limit)
   local width = vim.fn.winwidth(0)
   return width >= width_limit
@@ -451,12 +514,18 @@ function M.is_window_tall_enough(height_limit)
   local height = vim.fn.winheight(0)
   return height >= height_limit
 end
+
+--- Function to get the current date
+---@return string|osdate date The current date
 function M.get_date()
   return os.date("%Y-%m-%d")
 end
 
+--- Function to exit neovim
+---@return nil
 function M.exit()
   vim.api.nvim_command("wqall")
 end
 
+-- Export the module
 return M