From c38272222a4d4c9a8cd5e4731a6582c5a3bec7b2 Mon Sep 17 00:00:00 2001
From: Ottatop <ottatop1227@gmail.com>
Date: Mon, 28 Aug 2023 19:47:29 -0500
Subject: [PATCH] Add more documentation

---
 api/lua/output.lua | 12 ++++++++++++
 api/lua/tag.lua    | 33 +++++++++++++++++++++++++++++++++
 api/lua/window.lua |  9 +++++++++
 3 files changed, 54 insertions(+)

diff --git a/api/lua/output.lua b/api/lua/output.lua
index f103fe9..46e164b 100644
--- a/api/lua/output.lua
+++ b/api/lua/output.lua
@@ -1,8 +1,20 @@
 -- SPDX-License-Identifier: GPL-3.0-or-later
 
+---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 OutputModule
 local output_module = {}
 
+---An output object.
+---
+---This is a representation of your actual output to the config process.
+---It serves to make it easier to deal with your outputs, defining methods for getting properties and
+---helpers for things like positioning multiple monitors.
+---
+---This can be retrieved through that various `get` functions in the `OutputModule`.
 ---@classmod
 ---@class Output A display.
 ---@field private _name string The name of this output (or rather, of its connector).
diff --git a/api/lua/tag.lua b/api/lua/tag.lua
index b427a59..de1abe4 100644
--- a/api/lua/tag.lua
+++ b/api/lua/tag.lua
@@ -1,5 +1,34 @@
 -- SPDX-License-Identifier: GPL-3.0-or-later
 
+---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.
+---
+---Many of the functions in this module take Tag|TagTable|TagTableNamed|string.
+---This is a convenience so you don't have to get a tag object every time you want to do
+---something with tags.
+---
+---Instead, you can pass in either:
+--- - A string of the tag's name (ex. "1")
+---     - This will get the first tag with that name on the focused output.
+--- - A table where [1] is the name and [2] is the output (or its name) (ex. { "1", output.get_by_name("DP-1") })
+---     - This will get the first tag with that name on the specified output.
+--- - The same table as above, but keyed with `name` and `output` (ex. { name = "1", output = "DP-1" })
+---     - This is simply for those who want more clarity in their config.
+---
+---If you need to get tags beyond the first with the same name, use a `get` function and find what you need.
 ---@class TagModule
 local tag_module = {}
 
@@ -15,11 +44,15 @@ local tag_module = {}
 ---@alias TagTable { [1]: string, [2]: (string|Output)? }
 ---@alias TagTableNamed { name: string, output: (string|Output)? }
 
+---A tag object.
+---
+---This can be retrieved through the various `get` functions in the `TagModule`.
 ---@classmod
 ---@class Tag
 ---@field private _id integer The internal id of this tag.
 local tag = {}
 
+---@nodoc
 ---***You probably don't need to use this function.***
 ---
 ---Create a tag from `Tag|TagTable|TagTableNamed|string`.
diff --git a/api/lua/window.lua b/api/lua/window.lua
index f5c9836..7b7bd9d 100644
--- a/api/lua/window.lua
+++ b/api/lua/window.lua
@@ -1,8 +1,17 @@
 -- SPDX-License-Identifier: GPL-3.0-or-later
 
+---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 WindowModule
 local window_module = {}
 
+---A window object.
+---
+---This is a representation of an application window to the config process.
+---
+---You can retrieve windows through the various `get` function in the `WindowModule`.
 ---@classmod
 ---@class Window
 ---@field private _id integer The internal id of this window