diff --git a/api/lua/pinnacle/grpc/client.lua b/api/lua/pinnacle/grpc/client.lua index 5382fd7..14f79bb 100644 --- a/api/lua/pinnacle/grpc/client.lua +++ b/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) --- diff --git a/api/lua/pinnacle/grpc/protobuf.lua b/api/lua/pinnacle/grpc/protobuf.lua index 7c2c359..456dbf5 100644 --- a/api/lua/pinnacle/grpc/protobuf.lua +++ b/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 diff --git a/api/lua/pinnacle/output.lua b/api/lua/pinnacle/output.lua index 2e58cf6..409397f 100644 --- a/api/lua/pinnacle/output.lua +++ b/api/lua/pinnacle/output.lua @@ -168,11 +168,31 @@ local signal_name_to_SignalName = { connect = "OutputConnect", } ----@class OutputSignal ----@field connect fun(output: OutputHandle)? +---@class OutputSignal Signals related to output events. +---@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 ----@return SignalHandles +---Connect to an output signal. +--- +---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({}) diff --git a/api/lua/pinnacle/signal.lua b/api/lua/pinnacle/signal.lua index e0985cb..ea62015 100644 --- a/api/lua/pinnacle/signal.lua +++ b/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 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 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 ---@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) diff --git a/api/lua/pinnacle/tag.lua b/api/lua/pinnacle/tag.lua index fb4efbd..e707eed 100644 --- a/api/lua/pinnacle/tag.lua +++ b/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 ----@field layout fun(tag: TagHandle, windows: WindowHandle[])? +---@class TagSignal Signals related to tag events. +---@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 ----@return SignalHandles +---Connect to a tag signal. +--- +---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({}) diff --git a/api/lua/pinnacle/window.lua b/api/lua/pinnacle/window.lua index 266cf78..0cf5fff 100644 --- a/api/lua/pinnacle/window.lua +++ b/api/lua/pinnacle/window.lua @@ -316,12 +316,32 @@ local signal_name_to_SignalName = { pointer_leave = "WindowPointerLeave", } ----@class WindowSignal ----@field pointer_enter fun(window: WindowHandle)? ----@field pointer_leave fun(window: WindowHandle)? +---@class WindowSignal Signals related to compositor events. +---@field pointer_enter fun(window: WindowHandle)? The pointer entered a window. +---@field pointer_leave fun(window: WindowHandle)? The pointer left a window. ----@param signals WindowSignal ----@return SignalHandles +---Connect to a window signal. +--- +---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({})