From fbef4007ea25b28096600fb8bd2644fda48113a2 Mon Sep 17 00:00:00 2001 From: Ottatop Date: Sun, 14 Jan 2024 19:53:43 -0600 Subject: [PATCH] Add doc-gen comment stuff Somehow the doc-gen tool still works, kinda crazy --- api/lua_grpc/pinnacle.lua | 8 +++++++- api/lua_grpc/pinnacle/grpc/client.lua | 2 ++ api/lua_grpc/pinnacle/input.lua | 4 ++++ api/lua_grpc/pinnacle/input/keys.lua | 1 + api/lua_grpc/pinnacle/output.lua | 14 ++++++++++++++ api/lua_grpc/pinnacle/process.lua | 4 ++++ api/lua_grpc/pinnacle/tag.lua | 20 ++++++++++++++++++++ api/lua_grpc/pinnacle/window.lua | 14 ++++++++++++++ 8 files changed, 66 insertions(+), 1 deletion(-) diff --git a/api/lua_grpc/pinnacle.lua b/api/lua_grpc/pinnacle.lua index 6bd5ff0..33c9b93 100644 --- a/api/lua_grpc/pinnacle.lua +++ b/api/lua_grpc/pinnacle.lua @@ -2,12 +2,18 @@ local cqueues = require("cqueues") local client = require("pinnacle.grpc.client") +---The entry point to configuration. +--- +---This module contains one function: `setup`, which is how you'll access all the ways to configure Pinnacle. ---@class PinnacleModule local pinnacle = { version = "v0alpha1", } ----@classmod +---The Pinnacle module. +--- +---This module holds all the other configuration modules (Window, Input, etc.), and allows you to +---quit the compositor using the `quit` method. ---@class Pinnacle ---@field private config_client Client ---@field input Input diff --git a/api/lua_grpc/pinnacle/grpc/client.lua b/api/lua_grpc/pinnacle/grpc/client.lua index 343eadd..7e8148b 100644 --- a/api/lua_grpc/pinnacle/grpc/client.lua +++ b/api/lua_grpc/pinnacle/grpc/client.lua @@ -25,9 +25,11 @@ end ---@return integer total_length local function read_length_prefixed_message(body) end +---@nodoc ---@class ClientModule local client = {} +---@nodoc ---@class Client ---@field conn H2Connection ---@field loop CqueuesLoop diff --git a/api/lua_grpc/pinnacle/input.lua b/api/lua_grpc/pinnacle/input.lua index 7bd0d05..eb01343 100644 --- a/api/lua_grpc/pinnacle/input.lua +++ b/api/lua_grpc/pinnacle/input.lua @@ -92,11 +92,15 @@ local mouse_edge_values = { ---| "press" Trigger on mouse button press ---| "release" Trigger on mouse button release +---@nodoc ---@class InputModule ---@field private btn table local input = {} input.btn = mouse_button_values +---Input management. +--- +---This module provides utilities to set key- and mousebinds as well as change keyboard settings. ---@class Input ---@field private config_client Client local Input = { diff --git a/api/lua_grpc/pinnacle/input/keys.lua b/api/lua_grpc/pinnacle/input/keys.lua index 45c2a63..4116ef6 100644 --- a/api/lua_grpc/pinnacle/input/keys.lua +++ b/api/lua_grpc/pinnacle/input/keys.lua @@ -1,3 +1,4 @@ +---@nodoc ---@enum Key local keys = { NoSymbol = 0x00000000, diff --git a/api/lua_grpc/pinnacle/output.lua b/api/lua_grpc/pinnacle/output.lua index 75932d5..3555ab7 100644 --- a/api/lua_grpc/pinnacle/output.lua +++ b/api/lua_grpc/pinnacle/output.lua @@ -35,20 +35,34 @@ local function build_grpc_request_params(method, data) } end +---@nodoc ---@class OutputHandleModule local output_handle = {} +---An output handle. +--- +---This is a handle to one of your monitors. +---It serves to make it easier to deal with them, defining methods for getting properties and +---helpers for things like positioning multiple monitors. +--- +---This can be retrieved through the various `get` functions in the `Output` module. ---@classmod ---@class OutputHandle ---@field private config_client Client ---@field name string The unique name of this output local OutputHandle = {} +---@nodoc ---@class OutputModule ---@field private handle OutputHandleModule local output = {} output.handle = output_handle +---Output management. +--- +---An output is what you would call a monitor. It presents windows, your cursor, and other UI elements. +--- +---Outputs are uniquely identified by their name, a.k.a. the name of the connector they're plugged in to. ---@class Output ---@field private config_client Client local Output = {} diff --git a/api/lua_grpc/pinnacle/process.lua b/api/lua_grpc/pinnacle/process.lua index 4a0ac43..28c70f2 100644 --- a/api/lua_grpc/pinnacle/process.lua +++ b/api/lua_grpc/pinnacle/process.lua @@ -29,9 +29,13 @@ local function build_grpc_request_params(method, data) } end +---@nodoc ---@class ProcessModule local process = {} +---Process management. +--- +---This module provides utilities to spawn processes and capture their output. ---@class Process ---@field private config_client Client local Process = {} diff --git a/api/lua_grpc/pinnacle/tag.lua b/api/lua_grpc/pinnacle/tag.lua index cd716ac..d1b3914 100644 --- a/api/lua_grpc/pinnacle/tag.lua +++ b/api/lua_grpc/pinnacle/tag.lua @@ -41,6 +41,11 @@ end ---@class TagHandleModule local tag_handle = {} +---A tag handle. +--- +---This is a handle that allows manipulation of a tag. +--- +---This can be retrieved through the various `get` functions in the `Tag` module. ---@classmod ---@class TagHandle ---@field private config_client Client @@ -52,6 +57,21 @@ local TagHandle = {} local tag = {} tag.handle = tag_handle +---Tag management. +--- +---This module provides utilities for creating and manipulating tags. +--- +---A tag is a sort of marker for each of your windows. It allows you to present windows in ways that +---traditional workspaces cannot. +--- +---More specifically: +--- +--- - A window can have multiple tags. +--- - This means that you can have one window show up across multiple "workspaces" if you come something like i3. +--- - An output can display multiple tags at once. +--- - This allows you to toggle a tag and have windows on both tags display at once. This is helpful if you, say, want to reference a browser window while coding; you toggle your browser's tag and temporarily reference it while you work without having to change screens. +--- +---If you need to get tags beyond the first with the same name, use the `get` method and find what you need. ---@class Tag ---@field private config_client Client local Tag = {} diff --git a/api/lua_grpc/pinnacle/window.lua b/api/lua_grpc/pinnacle/window.lua index ff183d1..c6a628c 100644 --- a/api/lua_grpc/pinnacle/window.lua +++ b/api/lua_grpc/pinnacle/window.lua @@ -41,20 +41,34 @@ local function build_grpc_request_params(method, data) } end +---@nodoc ---@class WindowHandleModule local window_handle = {} +---A window handle. +--- +---This is a handle to an application window that allows manipulation of the window. +--- +---If the window is destroyed, the handle will become invalid and may not do +---what you want it to. +--- +---You can retrieve window handles through the various `get` functions in the `Window` module. ---@classmod ---@class WindowHandle ---@field private config_client Client ---@field id integer local WindowHandle = {} +---@nodoc ---@class WindowModule ---@field private handle WindowHandleModule local window = {} window.handle = window_handle +---Window management. +--- +---This module helps you deal with setting windows to fullscreen and maximized, setting their size, +---moving them between tags, and various other actions. ---@class Window ---@field private config_client Client local Window = {}