feat(utils): add type annotations and inline documentation to various utility modules

lua/utils/wakatime_stats.lua

@@ -6,8 +6,11 @@ local M = {}
 require("utils.cache_stats")
 local cache_file = os.getenv("HOME") .. "/.cache/wakatime_cache.txt"
 
+-- Local variable to store the last known value
 local last_known_value = ""
 
+--- Function to read the cache file
+---@return string content The content of the cache file
 local function read_cache()
   local file = io.open(cache_file, "r")
   if file then
@@ -19,26 +22,30 @@ local function read_cache()
   return last_known_value
 end
 
+--- Function to get the wakatime today cache
+---@return string status The wakatime today cache
 local function get_wakatime_today()
   local result = read_cache()
   if not result or result:match("^%s*$") then
     return last_known_value
   end
-
   if
     result:match("command not found")
     or result:match("No such file or directory")
   then
     return last_known_value
   end
-
   return result:match("^%s*(.-)%s*$") -- Trim any whitespace
 end
 
+--- Function to get the wakatime today status
+---@return string status The wakatime today status
 function M.get_today()
   return get_wakatime_today()
 end
 
+--- Function to get the wakatime today icon
+---@return string icon The wakatime today icon
 function M.get_icon()
   local text = M.get_today()
   if text ~= "" then
@@ -48,6 +55,8 @@ function M.get_icon()
   end
 end
 
+--- Function to get the wakatime today icon and text
+---@return string icon_and_text The wakatime today icon and text
 function M.get_icon_with_text()
   local icon = M.get_icon()
   local text = M.get_today()
@@ -58,28 +67,30 @@ function M.get_icon_with_text()
   end
 end
 
+--- Function to get the total minutes
+---@return number total_minutes The total minutes
 function M.get_total_minutes()
   local wakatime_string = M.get_today()
   if wakatime_string == "" then
     return 0 -- Return 0 if there's no data
   end
-
+  -- Extract hours and minutes from the wakatime string
   local hours, mins = wakatime_string:match("(%d+)%s*hrs?%s*(%d+)%s*mins?")
   if not hours then
     mins = wakatime_string:match("(%d+)%s*mins?")
     hours = 0
   end
-
+  -- Convert hours and minutes to total minutes
   hours = tonumber(hours) or 0
   mins = tonumber(mins) or 0
-
   return (hours * 60) + mins
 end
 
+--- Function to get the color based on the total minutes
+---@return table color The color based on the total minutes
 function M.get_color()
   local total_minutes = M.get_total_minutes()
-  local utils = require("utils.rootiest") -- Adjust according to your actual setup
-
+  local utils = require("data").func
   if total_minutes >= 60 then
     return { fg = utils.get_fg_color("GitSignsAdd") }
   elseif total_minutes >= 30 then