Clean up window documentation

api/lua/window.lua

@@ -30,12 +30,8 @@ end
 
 ---Set this window's size.
 ---
----### Examples
+---See `WindowModule.set_size` for examples.
----```lua
+---
----window.get_focused():set_size({ w = 500, h = 500 }) -- make the window square and 500 pixels wide/tall
----window.get_focused():set_size({ h = 300 })          -- keep the window's width but make it 300 pixels tall
----window.get_focused():set_size({})                   -- do absolutely nothing useful
----```
 ---@param size { w: integer?, h: integer? }
 ---@see WindowModule.set_size — The corresponding module function
 function window:set_size(size)
@@ -44,12 +40,8 @@ end
 
 ---Move this window to a tag, removing all other ones.
 ---
----### Example
+---See `WindowModule.move_to_tag` for examples.
----```lua
+---
------ With the focused window on tags 1, 2, 3, and 4...
----window.get_focused():move_to_tag("5")
------ ...will make the window only appear on tag 5.
----```
 ---@param name string
 ---@param output Output?
 ---@overload fun(self: self, t: Tag)
@@ -60,14 +52,9 @@ end
 
 ---Toggle the specified tag for this window.
 ---
----Note: toggling off all tags currently makes a window not response to layouting.
+---Note: toggling off all tags currently makes a window not respond to layouting.
 ---
----### Example
+---See `WindowModule.toggle_tag` for examples.
----```lua
------ With the focused window only on tag 1...
----window.get_focused():toggle_tag("2")
------ ...will also make the window appear on tag 2.
----```
 ---@param name string
 ---@param output Output?
 ---@overload fun(self: self, t: Tag)
@@ -81,10 +68,7 @@ end
 ---This only sends a close *event* to the window and is the same as just clicking the X button in the titlebar.
 ---This will trigger save prompts in applications like GIMP.
 ---
----### Example
+---See `WindowModule.close` for examples.
----```lua
----window.get_focused():close() -- close the currently focused window
----```
 ---@see WindowModule.close — The corresponding module function
 function window:close()
     window_module.close(self)
@@ -92,12 +76,7 @@ end
 
 ---Get this window's size.
 ---
----### Example
+---See `WindowModule.size` for examples.
----```lua
------ With a 4K monitor, given a focused fullscreen window...
----local size = window.get_focused():size()
------ ...should have size equal to `{ w = 3840, h = 2160 }`.
----```
 ---@return { w: integer, h: integer }|nil size The size of the window, or nil if it doesn't exist.
 ---@see WindowModule.size — The corresponding module function
 function window:size()
@@ -107,16 +86,12 @@ end
 ---Get this window's location in the global space.
 ---
 ---Think of your monitors as being laid out on a big sheet.
----The top left of the sheet if you trim it down is (0, 0).
+---The location of this window is relative inside the sheet.
----The location of this window is relative to that point.
 ---
----### Example
+---If you don't set the location of your monitors, they will start at (0, 0)
----```lua
+---and extend rightward with their tops aligned.
------ With two 1080p monitors side by side and set up as such,
+---
------ if a window is fullscreen on the right one...
+---See `WindowModule.loc` for examples.
----local loc = that_window:loc()
------ ...should have loc equal to `{ x = 1920, y = 0 }`.
----```
 ---@return { x: integer, y: integer }|nil loc The location of the window, or nil if it's not on-screen or alive.
 ---@see WindowModule.loc — The corresponding module function
 function window:loc()
@@ -125,12 +100,7 @@ end
 
 ---Get this window's class. This is usually the name of the application.
 ---
----### Example
+---See `WindowModule.class` for examples.
----```lua
------ With Alacritty focused...
----print(window.get_focused():class())
------ ...should print "Alacritty".
----```
 ---@return string|nil class This window's class, or nil if it doesn't exist.
 ---@see WindowModule.class — The corresponding module function
 function window:class()
@@ -139,12 +109,7 @@ end
 
 ---Get this window's title.
 ---
----### Example
+---See `WindowModule.title` for examples.
----```lua
------ With Alacritty focused...
----print(window.get_focused():title())
------ ...should print the directory Alacritty is in or what it's running (what's in its title bar).
----```
 ---@return string|nil title This window's title, or nil if it doesn't exist.
 ---@see WindowModule.title — The corresponding module function
 function window:title()
@@ -204,10 +169,7 @@ end
 
 ---Get whether or not this window is focused.
 ---
----### Example
+---See `WindowModule.focused` for examples.
----```lua
----print(window.get_focused():focused()) -- should print `true`.
----```
 ---@return boolean|nil
 ---@see WindowModule.focused — The corresponding module function
 function window:focused()
@@ -269,16 +231,20 @@ end
 function window_module.get_all()
     local window_ids =
         Request("GetWindows").RequestResponse.response.Windows.window_ids
+
     ---@type Window[]
     local windows = {}
+
     for _, window_id in pairs(window_ids) do
         table.insert(windows, create_window(window_id))
     end
+
     return windows
 end
 
 ---Toggle the tag with the given name and (optional) output for the specified window.
 ---You can also provide a tag object instead of a name and output.
+---
 ---@param w Window
 ---@param name string
 ---@param output Output?
@@ -475,8 +441,10 @@ end
 ---Get the specified window's location in the global space.
 ---
 ---Think of your monitors as being laid out on a big sheet.
----The top left of the sheet if you trim it down is (0, 0).
+---The location of this window is relative inside the sheet.
----The location of this window is relative to that point.
+---
+---If you don't set the location of your monitors, they will start at (0, 0)
+---and extend rightward with their tops aligned.
 ---
 ---### Example
 ---```lua