Add Lua docs

api/lua/pinnacle/grpc/client.lua

@@ -8,7 +8,6 @@ local h2_connection = require("http.h2_connection")
 local protobuf = require("pinnacle.grpc.protobuf")
 local pb = require("pb")
 
----@nodoc
 ---Create appropriate headers for a gRPC request.
 ---@param service string The desired service
 ---@param method string The desired method within the service
@@ -160,6 +159,7 @@ function client.server_streaming_request(grpc_request_params, callback)
     end)
 end
 
+---@nodoc
 ---@param grpc_request_params GrpcRequestParams
 ---@param callback fun(response: table)
 ---

api/lua/pinnacle/grpc/protobuf.lua

@@ -39,6 +39,7 @@ function protobuf.build_protos()
     pb.option("enum_as_value")
 end
 
+---@nodoc
 ---Encode the given `data` as the protobuf `type`.
 ---@param type string The absolute protobuf type
 ---@param data table The table of data, conforming to its protobuf definition

api/lua/pinnacle/output.lua

@@ -168,11 +168,31 @@ local signal_name_to_SignalName = {
     connect = "OutputConnect",
 }
 
----@class OutputSignal
+---@class OutputSignal Signals related to output events.
----@field connect fun(output: OutputHandle)?
+---@field connect fun(output: OutputHandle)? An output was connected. FIXME: This currently does not fire for outputs that have been previously connected and disconnected.
 
----@param signals OutputSignal
+---Connect to an output signal.
----@return SignalHandles
+---
+---The compositor sends signals about various events. Use this function to run a callback when
+---some output signal occurs.
+---
+---This function returns a table of signal handles with each handle stored at the same key used
+---to connect to the signal. See `SignalHandles` for more information.
+---
+---# Example
+---```lua
+---Output.connect_signal({
+---    connect = function(output)
+---        print("New output connected:", output.name)
+---    end
+---})
+---```
+---
+---@param signals OutputSignal The signal you want to connect to
+---
+---@return SignalHandles signal_handles Handles to every signal you connected to wrapped in a table, with keys being the same as the connected signal.
+---
+---@see SignalHandles.disconnect_all - To disconnect from these signals
 function output.connect_signal(signals)
     ---@diagnostic disable-next-line: invisible
     local handles = require("pinnacle.signal").handles.new({})

api/lua/pinnacle/signal.lua

@@ -49,37 +49,51 @@ local stream_control = {
     DISCONNECT = 2,
 }
 
+-- TODO: rewrite ldoc_gen so you don't have to stick @nodoc everywhere
+
 ---@type table<SignalServiceMethod, { sender: H2Stream?, callbacks: function[], on_response: fun(response: table) }>
 local signals = {
     OutputConnect = {
+        ---@nodoc
         ---@type H2Stream?
         sender = nil,
+        ---@nodoc
         ---@type (fun(output: OutputHandle))[]
         callbacks = {},
+        ---@nodoc
         ---@type fun(response: table)
         on_response = nil,
     },
     Layout = {
+        ---@nodoc
         ---@type H2Stream?
         sender = nil,
+        ---@nodoc
         ---@type (fun(tag: TagHandle, windows: WindowHandle[]))[]
         callbacks = {},
+        ---@nodoc
         ---@type fun(response: table)
         on_response = nil,
     },
     WindowPointerEnter = {
+        ---@nodoc
         ---@type H2Stream?
         sender = nil,
+        ---@nodoc
         ---@type (fun(window: WindowHandle))[]
         callbacks = {},
+        ---@nodoc
         ---@type fun(response: table)
         on_response = nil,
     },
     WindowPointerLeave = {
+        ---@nodoc
         ---@type H2Stream?
         sender = nil,
+        ---@nodoc
         ---@type (fun(window: WindowHandle))[]
         callbacks = {},
+        ---@nodoc
         ---@type fun(response: table)
         on_response = nil,
     },
@@ -124,20 +138,26 @@ end
 
 -----------------------------------------------------------------------------
 
+---@nodoc
 ---@class SignalHandleModule
 local signal_handle = {}
 
+---A handle to a connected signal that can be used to disconnect the provided callback.
+---
 ---@class SignalHandle
 ---@field signal SignalServiceMethod
 ---@field callback function The callback you connected
 local SignalHandle = {}
 
+---@nodoc
 ---@class SignalHandlesModule
 local signal_handles = {}
 
+---@nodoc
 ---@class SignalHandles
 local SignalHandles = {}
 
+---@nodoc
 ---@class Signal
 ---@field private handle SignalHandleModule
 ---@field private handles SignalHandlesModule
@@ -145,6 +165,7 @@ local signal = {}
 signal.handle = signal_handle
 signal.handles = signal_handles
 
+---@nodoc
 function SignalHandle:disconnect()
     local cb_index = nil
     for i, cb in ipairs(signals[self.signal].callbacks) do
@@ -163,6 +184,7 @@ function SignalHandle:disconnect()
     end
 end
 
+---@nodoc
 ---@return SignalHandle
 function signal_handle.new(request, callback)
     ---@type SignalHandle
@@ -174,6 +196,8 @@ function signal_handle.new(request, callback)
     return self
 end
 
+---Disconnect the callbacks from all the signal connections that are stored in this handle collection.
+---
 ---@param self table<string, SignalHandle>
 function SignalHandles:disconnect_all()
     for _, sig in pairs(self) do
@@ -181,6 +205,7 @@ function SignalHandles:disconnect_all()
     end
 end
 
+---@nodoc
 ---@param signal_hdls table<string, SignalHandle>
 ---@return SignalHandles
 function signal_handles.new(signal_hdls)
@@ -190,6 +215,7 @@ function signal_handles.new(signal_hdls)
     return self
 end
 
+---@nodoc
 ---@param request SignalServiceMethod
 ---@param callback function
 function signal.add_callback(request, callback)
@@ -200,6 +226,7 @@ function signal.add_callback(request, callback)
     table.insert(signals[request].callbacks, callback)
 end
 
+---@nodoc
 ---@param request SignalServiceMethod
 ---@param callback fun(response: table)
 function signal.connect(request, callback)
@@ -228,6 +255,7 @@ function signal.connect(request, callback)
     signals[request].sender = stream
 end
 
+---@nodoc
 ---This should only be called when call callbacks for the signal are removed
 ---@param request SignalServiceMethod
 function signal.disconnect(request)

api/lua/pinnacle/tag.lua

@@ -234,8 +234,8 @@ end
 ---layout_cycler.next() -- Layout is now "dwindle"
 ---layout_cycler.next() -- Layout is now "corner_top_left"
 ---layout_cycler.next() -- Layout is now "corner_top_right"
+---layout_cycler.next() -- Layout is now "master_stack"
 ---layout_cycler.next() -- Layout is now "dwindle"
----layout_cycler.next() -- Layout is now "corner_top_right"
 ---
 --- -- Cycling on another output
 ---layout_cycler.next(Output.get_by_name("eDP-1"))
@@ -323,11 +323,31 @@ local signal_name_to_SignalName = {
     layout = "Layout",
 }
 
----@class TagSignal
+---@class TagSignal Signals related to tag events.
----@field layout fun(tag: TagHandle, windows: WindowHandle[])?
+---@field layout fun(tag: TagHandle, windows: WindowHandle[])? The compositor requested a layout of the given tiled windows. You'll also receive the first active tag.
 
----@param signals TagSignal
+---Connect to a tag signal.
----@return SignalHandles
+---
+---The compositor sends signals about various events. Use this function to run a callback when
+---some tag signal occurs.
+---
+---This function returns a table of signal handles with each handle stored at the same key used
+---to connect to the signal. See `SignalHandles` for more information.
+---
+---# Example
+---```lua
+---Tag.connect_signal({
+---    layout = function(tag, windows)
+---        print("Compositor requested a layout")
+---    end
+---})
+---```
+---
+---@param signals TagSignal The signal you want to connect to
+---
+---@return SignalHandles signal_handles Handles to every signal you connected to wrapped in a table, with keys being the same as the connected signal.
+---
+---@see SignalHandles.disconnect_all - To disconnect from these signals
 function tag.connect_signal(signals)
     ---@diagnostic disable-next-line: invisible
     local handles = require("pinnacle.signal").handles.new({})

api/lua/pinnacle/window.lua

@@ -316,12 +316,32 @@ local signal_name_to_SignalName = {
     pointer_leave = "WindowPointerLeave",
 }
 
----@class WindowSignal
+---@class WindowSignal Signals related to compositor events.
----@field pointer_enter fun(window: WindowHandle)?
+---@field pointer_enter fun(window: WindowHandle)? The pointer entered a window.
----@field pointer_leave fun(window: WindowHandle)?
+---@field pointer_leave fun(window: WindowHandle)? The pointer left a window.
 
----@param signals WindowSignal
+---Connect to a window signal.
----@return SignalHandles
+---
+---The compositor sends signals about various events. Use this function to run a callback when
+---some window signal occurs.
+---
+---This function returns a table of signal handles with each handle stored at the same key used
+---to connect to the signal. See `SignalHandles` for more information.
+---
+---# Example
+---```lua
+---Window.connect_signal({
+---    pointer_enter = function(window)
+---        print("Pointer entered", window:class())
+---    end
+---})
+---```
+---
+---@param signals WindowSignal The signal you want to connect to
+---
+---@return SignalHandles signal_handles Handles to every signal you connected to wrapped in a table, with keys being the same as the connected signal.
+---
+---@see SignalHandles.disconnect_all - To disconnect from these signals
 function window.connect_signal(signals)
     ---@diagnostic disable-next-line: invisible
     local handles = require("pinnacle.signal").handles.new({})