From 028485d68fbb88e5b7e1239f9cda01c1672cd9c9 Mon Sep 17 00:00:00 2001
From: Squibid <me@zacharyscheiman.com>
Date: Sun, 30 Nov 2025 23:49:19 -0500
Subject: [PATCH] more lua docs for zlua functions

---
 src/lua/fs.zig     |  3 +++
 src/lua/hook.zig   |  3 +++
 src/lua/input.zig  |  7 +++++++
 src/lua/output.zig | 52 +++++++++++++++++++++++-----------------------
 4 files changed, 39 insertions(+), 26 deletions(-)

diff --git a/src/lua/fs.zig b/src/lua/fs.zig
index 3e5ea2c..17621ab 100644
--- a/src/lua/fs.zig
+++ b/src/lua/fs.zig
@@ -7,6 +7,9 @@ const Lua = @import("lua.zig");
 
 const gpa = std.heap.c_allocator;
 
+/// ---Join any number of paths into one path
+/// ---@vararg string paths to join
+/// ---@return string?
 pub fn joinpath(L: *zlua.Lua) i32 {
   const nargs: i32 = L.getTop();
   if (nargs < 2) {
diff --git a/src/lua/hook.zig b/src/lua/hook.zig
index 8bd0f37..e02989d 100644
--- a/src/lua/hook.zig
+++ b/src/lua/hook.zig
@@ -9,6 +9,9 @@ const Utils = @import("../utils.zig");
 const gpa = std.heap.c_allocator;
 const server = &@import("../main.zig").server;
 
+/// ---Create a new hook on an event
+/// ---@param string|string[] event(s)
+/// ---@param table options
 pub fn add(L: *zlua.Lua) i32 {
   L.checkType(2, .table);
 
diff --git a/src/lua/input.zig b/src/lua/input.zig
index c43acd2..e90bbab 100644
--- a/src/lua/input.zig
+++ b/src/lua/input.zig
@@ -24,6 +24,10 @@ fn parse_modkeys(modStr: []const u8) wlr.Keyboard.ModifierMask {
   return modifiers;
 }
 
+/// ---Create a new keymap
+/// ---@param string modifiers
+/// ---@param string keys
+/// ---@param table options
 pub fn add_keymap(L: *zlua.Lua) i32 {
   var keymap: Keymap = undefined;
   keymap.options.repeat = true;
@@ -61,6 +65,9 @@ pub fn add_keymap(L: *zlua.Lua) i32 {
   return 1;
 }
 
+/// ---Remove an existing keymap
+/// ---@param string modifiers
+/// ---@param string keys
 pub fn del_keymap(L: *zlua.Lua) i32 {
   L.checkType(1, .string);
   L.checkType(2, .string);
diff --git a/src/lua/output.zig b/src/lua/output.zig
index 2f9d149..305530f 100644
--- a/src/lua/output.zig
+++ b/src/lua/output.zig
@@ -5,10 +5,10 @@ const Output = @import("../output.zig");
 
 const server = &@import("../main.zig").server;
 
-// ---@alias output_id integer
+/// ---@alias output_id integer
 
-// ---Get the ids for all available outputs
-// ---@return output_id[]?
+/// ---Get the ids for all available outputs
+/// ---@return output_id[]?
 pub fn get_all_ids(L: *zlua.Lua) i32 {
   var it = server.root.scene.outputs.iterator(.forward);
   var index: usize = 1;
@@ -28,8 +28,8 @@ pub fn get_all_ids(L: *zlua.Lua) i32 {
   return 1;
 }
 
-// ---Get the id for the focused output
-// ---@return output_id?
+/// ---Get the id for the focused output
+/// ---@return output_id?
 pub fn get_focused_id(L: *zlua.Lua) i32 {
   if(server.seat.focused_output) |output| {
     L.pushInteger(@intCast(output.id));
@@ -40,9 +40,9 @@ pub fn get_focused_id(L: *zlua.Lua) i32 {
   return 1;
 }
 
-// ---Get refresh rate for the output
-// ---@param output_id output_id 0 maps to focused output
-// ---@return integer?
+/// ---Get refresh rate for the output
+/// ---@param output_id output_id 0 maps to focused output
+/// ---@return integer?
 pub fn get_rate(L: *zlua.Lua) i32 {
   const output_id: u64 = @intCast(L.checkInteger(1));
 
@@ -56,9 +56,9 @@ pub fn get_rate(L: *zlua.Lua) i32 {
   return 1;
 }
 
-// ---Get resolution in pixels of the output
-// ---@param output_id output_id 0 maps to focused output
-// ---@return { width: integer, height: integer }?
+/// ---Get resolution in pixels of the output
+/// ---@param output_id output_id 0 maps to focused output
+/// ---@return { width: integer, height: integer }?
 pub fn get_resolution(L: *zlua.Lua) i32 {
   const output_id: u64 = @intCast(L.checkInteger(1));
 
@@ -81,9 +81,9 @@ pub fn get_resolution(L: *zlua.Lua) i32 {
   return 1;
 }
 
-// ---Get the serial for the output
-// ---@param output_id output_id 0 maps to focused output
-// ---@return string?
+/// ---Get the serial for the output
+/// ---@param output_id output_id 0 maps to focused output
+/// ---@return string?
 pub fn get_serial(L: *zlua.Lua) i32 {
   const output_id: u64 = @intCast(L.checkInteger(1));
 
@@ -102,9 +102,9 @@ pub fn get_serial(L: *zlua.Lua) i32 {
   return 1;
 }
 
-// ---Get the make for the output
-// ---@param output_id output_id 0 maps to focused output
-// ---@return string?
+/// ---Get the make for the output
+/// ---@param output_id output_id 0 maps to focused output
+/// ---@return string?
 pub fn get_make(L: *zlua.Lua) i32 {
   const output_id: u64 = @intCast(L.checkInteger(1));
 
@@ -123,9 +123,9 @@ pub fn get_make(L: *zlua.Lua) i32 {
   return 1;
 }
 
-// ---Get the model for the output
-// ---@param output_id output_id 0 maps to focused output
-// ---@return stirng?
+/// ---Get the model for the output
+/// ---@param output_id output_id 0 maps to focused output
+/// ---@return stirng?
 pub fn get_model(L: *zlua.Lua) i32 {
   const output_id: u64 = @intCast(L.checkInteger(1));
 
@@ -144,9 +144,9 @@ pub fn get_model(L: *zlua.Lua) i32 {
   return 1;
 }
 
-// ---Get the description for the output
-// ---@param output_id output_id 0 maps to focused output
-// ---@return stirng?
+/// ---Get the description for the output
+/// ---@param output_id output_id 0 maps to focused output
+/// ---@return stirng?
 pub fn get_description(L: *zlua.Lua) i32 {
   const output_id: u64 = @intCast(L.checkInteger(1));
 
@@ -165,9 +165,9 @@ pub fn get_description(L: *zlua.Lua) i32 {
   return 1;
 }
 
-// ---Get the description for the output
-// ---@param output_id output_id 0 maps to focused output
-// ---@return stirng
+/// ---Get the description for the output
+/// ---@param output_id output_id 0 maps to focused output
+/// ---@return stirng
 pub fn get_name(L: *zlua.Lua) i32 {
   const output_id: u64 = @intCast(L.checkInteger(1));