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/links.lua | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

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

diff --git a/lua/muwiki/links.lua b/lua/muwiki/links.lua
index 17fed65..2972973 100644
--- a/lua/muwiki/links.lua
+++ b/lua/muwiki/links.lua
@@ -3,6 +3,16 @@ local config = require('muwiki.config')
 
 local M = {}
 
+---@class Link
+---@field text string Display text of the link
+---@field target string Link destination (URL or path)
+---@field type 'web'|'file'|'wiki' Type of link
+
+---@class Handler
+---@field name string Display name of the handler
+---@field cmd string|function Command or function to handle the URL
+---@field exts string[]? Optional list of file extensions this handler supports
+
 local function is_text_extension(ext)
   local text_exts = config.options.text_extensions or {}
   ext = ext:gsub("^%.", "")
@@ -25,6 +35,8 @@ local function get_link_type(target)
   return 'wiki'
 end
 
+---Get link information at cursor position
+---@return Link|nil link_info Table with text, target, and type, or nil if no link found
 function M.get_link()
   local cursor = vim.api.nvim_win_get_cursor(0)
 
@@ -70,6 +82,10 @@ function M.get_link()
   }
 end
 
+---Open the link under cursor
+---Uses xdg-open for web links and unmatched file:// links
+---Opens matching text_extensions in Neovim buffer
+---Wiki links always open in Neovim
 function M.open_link()
   local link = M.get_link()
   if not link then
@@ -97,6 +113,9 @@ function M.open_link()
   utils.open_in_buffer(file_path)
 end
 
+---Open link with a selectable handler from a menu
+---@param handlers Handler[] List of handler tables with name, cmd, and optional exts
+---@param link Link? Optional pre-fetched link info, will get from cursor if not provided
 function M.open_with_menu(handlers, link)
   link = link or M.get_link()
   if not link then
@@ -150,6 +169,9 @@ function M.open_with_menu(handlers, link)
   end)
 end
 
+---Create a link from visual selection
+---Converts selected text to [text](normalized_text.md)
+---Must be called in visual mode
 function M.create_link()
   local mode = vim.fn.mode()
   if mode ~= 'v' and mode ~= 'V' then
@@ -209,6 +231,8 @@ function M.create_link()
   utils.open_in_buffer(target_path)
 end
 
+---Jump to next or previous markdown link in buffer
+---@param direction 'next'|'prev' Direction to search
 function M.jump_link(direction)
   local flags = direction == 'next' and 'w' or 'bw'
   local msg = direction == 'next' and 'No more links' or 'No previous links'
-- 
cgit v1.2.3