From 379e5af690c8ab298ef5d32fcaddae070c4ff8a5 Mon Sep 17 00:00:00 2001
From: moxie <moxie@3kgcat.fi>
Date: Mon, 16 Mar 2026 01:55:07 +0200
Subject: chore: add LuaCATS type annotations

---
 lua/muwiki/utils.lua | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

(limited to 'lua/muwiki/utils.lua')

diff --git a/lua/muwiki/utils.lua b/lua/muwiki/utils.lua
index c3da4eb..5330e41 100644
--- a/lua/muwiki/utils.lua
+++ b/lua/muwiki/utils.lua
@@ -2,11 +2,15 @@ local config = require('muwiki.config')
 
 local M = {}
 
+---Open a file in Neovim buffer
+---@param filepath string Absolute path to file
 function M.open_in_buffer(filepath)
   vim.cmd.edit(vim.fn.fnameescape(filepath))
 end
 
--- Lookup wiki path by name (e.g., "default" -> "~/wiki/")
+---Lookup wiki path by name
+---@param name string? Wiki name (uses first configured wiki if nil)
+---@return string|nil path Absolute path to wiki directory, or nil if not configured
 function M.wiki_path(name)
   if not config.options.dirs or #config.options.dirs == 0 then
     vim.notify('MuWiki: No dirs configured. See :help muwiki-configuration', vim.log.levels.ERROR)
@@ -25,7 +29,9 @@ function M.wiki_path(name)
   return config.options.dirs[1].path
 end
 
--- Find which wiki contains this buffer's file (cached per-buffer)
+---Find which wiki contains this buffer's file (cached per-buffer)
+---@param bufnr integer? Buffer number (defaults to 0 for current buffer)
+---@return string|nil path Absolute path to wiki root, or nil if buffer is not in a wiki
 function M.wiki_root(bufnr)
   bufnr = bufnr or 0
 
@@ -47,6 +53,8 @@ function M.wiki_root(bufnr)
   return nil
 end
 
+---Open the index file of a wiki
+---@param name string? Wiki name (uses first configured wiki if nil)
 function M.open_index(name)
   local wiki_path = M.wiki_path(name)
   if not wiki_path then
@@ -57,6 +65,10 @@ function M.open_index(name)
   M.open_in_buffer(index_path)
 end
 
+---Resolve a path to absolute normalized form
+---Strips file:// prefix and resolves relative paths against current buffer
+---@param filepath string Path to resolve (can include file://, be relative, absolute, or ~)
+---@return string Absolute normalized path
 function M.resolve(filepath)
   local path = filepath:gsub('^file://', '')
 
@@ -70,6 +82,10 @@ function M.resolve(filepath)
   return vim.fs.normalize(vim.fs.joinpath(current_dir, path))
 end
 
+---Normalize text for use as filename
+---Converts to lowercase, spaces to underscores, removes special chars
+---@param text string Text to normalize
+---@return string Normalized filename-safe text
 function M.normalize_filename(text)
   local normalized = text:lower()
   normalized = normalized:gsub('%s+', '_')
-- 
cgit v1.2.3