From ede03f61bf68c2b6c1f795e20c0ddcec785bf83a Mon Sep 17 00:00:00 2001
From: end-4 <97237370+end-4@users.noreply.github.com>
Date: Mon, 26 May 2025 10:46:07 +0200
Subject: [PATCH] provide basic descriptions for services

---
 .config/quickshell/services/AiMessageData.qml       |  3 +++
 .config/quickshell/services/AppSearch.qml           |  3 +++
 .config/quickshell/services/Audio.qml               |  3 +++
 .config/quickshell/services/Bluetooth.qml           |  3 +++
 .config/quickshell/services/Booru.qml               |  3 +++
 .config/quickshell/services/BooruResponseData.qml   |  3 +++
 .config/quickshell/services/Brightness.qml          |  5 ++++-
 .config/quickshell/services/ConfigLoader.qml        |  5 +++++
 .config/quickshell/services/DateTime.qml            |  3 +++
 .config/quickshell/services/HyprlandData.qml        |  3 +++
 .config/quickshell/services/HyprlandKeybinds.qml    | 13 +++++++++----
 .config/quickshell/services/KeyringStorage.qml      |  7 ++++---
 .config/quickshell/services/LatexRenderer.qml       | 12 ++++++------
 .config/quickshell/services/MaterialThemeLoader.qml |  4 ++++
 .config/quickshell/services/MprisController.qml     |  6 ++++++
 .config/quickshell/services/Network.qml             |  3 +++
 .config/quickshell/services/Notifications.qml       |  6 ++++++
 .../quickshell/services/PersistentStateManager.qml  |  4 ++++
 .config/quickshell/services/ResourceUsage.qml       |  3 +++
 .config/quickshell/services/SystemInfo.qml          |  3 +++
 .config/quickshell/services/Todo.qml                |  4 ++++
 21 files changed, 85 insertions(+), 14 deletions(-)

diff --git a/.config/quickshell/services/AiMessageData.qml b/.config/quickshell/services/AiMessageData.qml
index 625818a05..daac9f3ae 100644
--- a/.config/quickshell/services/AiMessageData.qml
+++ b/.config/quickshell/services/AiMessageData.qml
@@ -1,6 +1,9 @@
 import "root:/modules/common"
 import QtQuick;
 
+/**
+ * Represents a message in an AI conversation. (Kind of) follows the OpenAI API message structure.
+ */
 QtObject {
     property string role
     property string content
diff --git a/.config/quickshell/services/AppSearch.qml b/.config/quickshell/services/AppSearch.qml
index 1ecaa886c..10a54f835 100644
--- a/.config/quickshell/services/AppSearch.qml
+++ b/.config/quickshell/services/AppSearch.qml
@@ -4,6 +4,9 @@ import "root:/modules/common/functions/fuzzysort.js" as Fuzzy
 import Quickshell
 import Quickshell.Io
 
+/**
+ * Eases searching for applications by name.
+ */
 Singleton {
     id: root
 
diff --git a/.config/quickshell/services/Audio.qml b/.config/quickshell/services/Audio.qml
index 564c8afc2..8b5f9b760 100644
--- a/.config/quickshell/services/Audio.qml
+++ b/.config/quickshell/services/Audio.qml
@@ -4,6 +4,9 @@ import Quickshell.Services.Pipewire
 pragma Singleton
 pragma ComponentBehavior: Bound
 
+/**
+ * A nice wrapper for default Pipewire audio sink and source.
+ */
 Singleton {
     id: root
 
diff --git a/.config/quickshell/services/Bluetooth.qml b/.config/quickshell/services/Bluetooth.qml
index fed333bb5..817bbc921 100644
--- a/.config/quickshell/services/Bluetooth.qml
+++ b/.config/quickshell/services/Bluetooth.qml
@@ -5,6 +5,9 @@ import Quickshell;
 import Quickshell.Io;
 import QtQuick;
 
+/**
+ * Basic polled Bluetooth state.
+ */
 Singleton {
     id: root
 
diff --git a/.config/quickshell/services/Booru.qml b/.config/quickshell/services/Booru.qml
index 216fc1f5e..697e92069 100644
--- a/.config/quickshell/services/Booru.qml
+++ b/.config/quickshell/services/Booru.qml
@@ -7,6 +7,9 @@ import Quickshell.Io;
 import Qt.labs.platform
 import QtQuick;
 
+/**
+ * A service for interacting with various booru APIs.
+ */
 Singleton {
     id: root
     property Component booruResponseDataComponent: BooruResponseData {}
diff --git a/.config/quickshell/services/BooruResponseData.qml b/.config/quickshell/services/BooruResponseData.qml
index f0409a1ba..38e1b8c76 100644
--- a/.config/quickshell/services/BooruResponseData.qml
+++ b/.config/quickshell/services/BooruResponseData.qml
@@ -1,6 +1,9 @@
 import "root:/modules/common"
 import QtQuick;
 
+/**
+ * A booru response.
+ */
 QtObject {
     property string provider
     property var tags
diff --git a/.config/quickshell/services/Brightness.qml b/.config/quickshell/services/Brightness.qml
index 301584d3a..132f0eda9 100644
--- a/.config/quickshell/services/Brightness.qml
+++ b/.config/quickshell/services/Brightness.qml
@@ -1,7 +1,7 @@
 pragma Singleton
 pragma ComponentBehavior: Bound
 
-// From https://github.com/caelestia-dots/shell/ (`quickshell` branch)
+// From https://github.com/caelestia-dots/shell/ (`quickshell` branch) with modifications.
 // It does not have a license, but the author has given permission.
 
 import Quickshell
@@ -9,6 +9,9 @@ import Quickshell.Io
 import Quickshell.Hyprland
 import QtQuick
 
+/**
+ * For managing brightness of monitors. Supports both brightnessctl and ddcutil.
+ */
 Singleton {
     id: root
 
diff --git a/.config/quickshell/services/ConfigLoader.qml b/.config/quickshell/services/ConfigLoader.qml
index 6c330c68e..658019f19 100644
--- a/.config/quickshell/services/ConfigLoader.qml
+++ b/.config/quickshell/services/ConfigLoader.qml
@@ -10,6 +10,11 @@ import Quickshell.Io
 import Quickshell.Hyprland
 import Qt.labs.platform
 
+/**
+ * Loads and manages the shell configuration file.
+ * The config file is by default at XDG_CONFIG_HOME/illogical-impulse/config.json.
+ * Automatically reloaded when the file changes, but does not provide a way to save changes.
+ */
 Singleton {
     id: root
     property string fileDir: `${XdgDirectories.config}/illogical-impulse`
diff --git a/.config/quickshell/services/DateTime.qml b/.config/quickshell/services/DateTime.qml
index ee5cf4b41..36eb7a4a1 100644
--- a/.config/quickshell/services/DateTime.qml
+++ b/.config/quickshell/services/DateTime.qml
@@ -5,6 +5,9 @@ import Quickshell.Io
 pragma Singleton
 pragma ComponentBehavior: Bound
 
+/**
+ * A nice wrapper for date and time strings.
+ */
 Singleton {
     property string time: Qt.formatDateTime(clock.date, "hh:mm")
     property string date: Qt.formatDateTime(clock.date, "dddd, dd/MM")
diff --git a/.config/quickshell/services/HyprlandData.qml b/.config/quickshell/services/HyprlandData.qml
index d72c1a041..2b88ad9cc 100644
--- a/.config/quickshell/services/HyprlandData.qml
+++ b/.config/quickshell/services/HyprlandData.qml
@@ -7,6 +7,9 @@ import Quickshell.Io
 import Quickshell.Wayland
 import Quickshell.Hyprland
 
+/**
+ * Provides access to some Hyprland data not available in Quickshell.Hyprland.
+ */
 Singleton {
     id: root
     property var windowList: []
diff --git a/.config/quickshell/services/HyprlandKeybinds.qml b/.config/quickshell/services/HyprlandKeybinds.qml
index 1b2972fe9..f0001fe20 100644
--- a/.config/quickshell/services/HyprlandKeybinds.qml
+++ b/.config/quickshell/services/HyprlandKeybinds.qml
@@ -9,8 +9,15 @@ import Quickshell.Io
 import Quickshell.Wayland
 import Quickshell.Hyprland
 
+/**
+ * A service that provides access to Hyprland keybinds.
+ * Uses the `get_keybinds.py` script to parse comments in config files in a certain format and convert to JSON.
+ */
 Singleton {
     id: root
+    property string keybindParserPath: FileUtils.trimFileProtocol(`${XdgDirectories.config}/quickshell/scripts/hyprland/get_keybinds.py`)
+    property string defaultKeybindConfigPath: FileUtils.trimFileProtocol(`${XdgDirectories.config}/hypr/hyprland/keybinds.conf`)
+    property string userKeybindConfigPath: FileUtils.trimFileProtocol(`${XdgDirectories.config}/hypr/custom/keybinds.conf`)
     property var defaultKeybinds: {"children": []}
     property var userKeybinds: {"children": []}
     property var keybinds: ({
@@ -34,8 +41,7 @@ Singleton {
     Process {
         id: getDefaultKeybinds
         running: true
-        command: [FileUtils.trimFileProtocol(`${XdgDirectories.config}/quickshell/scripts/hyprland/get_keybinds.py`), 
-            "--path", FileUtils.trimFileProtocol(`${XdgDirectories.config}/hypr/hyprland/keybinds.conf`),]
+        command: [root.keybindParserPath, "--path", root.defaultKeybindConfigPath,]
         
         stdout: SplitParser {
             onRead: data => {
@@ -51,8 +57,7 @@ Singleton {
     Process {
         id: getUserKeybinds
         running: true
-        command: [FileUtils.trimFileProtocol(`${XdgDirectories.config}/quickshell/scripts/hyprland/get_keybinds.py`), 
-            "--path", FileUtils.trimFileProtocol(`${XdgDirectories.config}/hypr/custom/keybinds.conf`),]
+        command: [root.keybindParserPath, "--path", root.userKeybindConfigPath]
         
         stdout: SplitParser {
             onRead: data => {
diff --git a/.config/quickshell/services/KeyringStorage.qml b/.config/quickshell/services/KeyringStorage.qml
index 0de619100..3f3956f98 100644
--- a/.config/quickshell/services/KeyringStorage.qml
+++ b/.config/quickshell/services/KeyringStorage.qml
@@ -8,14 +8,15 @@ import Quickshell.Io;
 import Qt.labs.platform
 import QtQuick;
 
+/**
+ * For storing sensitive data in the keyring.
+ * Use this for small data only, since it stores a JSON of the contents directly and doesn't use a database.
+ */
 Singleton {
     id: root
 
     property bool loaded: false
     property var keyringData: ({})
-    // onKeyringDataChanged: {
-    //     console.log("[KeyringStorage] Keyring data changed:", JSON.stringify(root.keyringData));
-    // }
     
     property var properties: {
         "application": "illogical-impulse",
diff --git a/.config/quickshell/services/LatexRenderer.qml b/.config/quickshell/services/LatexRenderer.qml
index 9fb5fb0ab..c09f0af99 100644
--- a/.config/quickshell/services/LatexRenderer.qml
+++ b/.config/quickshell/services/LatexRenderer.qml
@@ -11,12 +11,12 @@ import Quickshell.Hyprland
 import Qt.labs.platform
 
 /**
-* Renders LaTeX snippets with MicroTeX.
-* For every request:
-*   1. Hash it
-*   2. Check if the hash is already processed
-*   3. If not, render it with MicroTeX and mark as processed
-*/
+ * Renders LaTeX snippets with MicroTeX.
+ * For every request:
+ *   1. Hash it
+ *   2. Check if the hash is already processed
+ *   3. If not, render it with MicroTeX and mark as processed
+ */
 Singleton {
     id: root
     
diff --git a/.config/quickshell/services/MaterialThemeLoader.qml b/.config/quickshell/services/MaterialThemeLoader.qml
index 339a0d772..dcee32c26 100644
--- a/.config/quickshell/services/MaterialThemeLoader.qml
+++ b/.config/quickshell/services/MaterialThemeLoader.qml
@@ -6,6 +6,10 @@ import QtQuick
 import Quickshell
 import Quickshell.Io
 
+/**
+ * Automatically reloads generated material colors.
+ * It is necessary to run reapplyTheme() on startup because Singletons are lazily loaded.
+ */
 Singleton {
     id: root
     property string filePath: `${XdgDirectories.state}/user/generated/colors.json`
diff --git a/.config/quickshell/services/MprisController.qml b/.config/quickshell/services/MprisController.qml
index 00ef982fc..96aa5e80b 100644
--- a/.config/quickshell/services/MprisController.qml
+++ b/.config/quickshell/services/MprisController.qml
@@ -1,12 +1,18 @@
 pragma Singleton
 pragma ComponentBehavior: Bound
 
+// From https://git.outfoxxed.me/outfoxxed/nixnew
+// It does not have a license, but the author is okay with redistribution.
+
 import QtQml.Models
 import QtQuick
 import Quickshell
 import Quickshell.Io
 import Quickshell.Services.Mpris
 
+/**
+ * A service that provides easy access to the active Mpris player.
+ */
 Singleton {
 	id: root;
 	property MprisPlayer trackedPlayer: null;
diff --git a/.config/quickshell/services/Network.qml b/.config/quickshell/services/Network.qml
index e790c39bc..e2f98005b 100644
--- a/.config/quickshell/services/Network.qml
+++ b/.config/quickshell/services/Network.qml
@@ -6,6 +6,9 @@ import Quickshell.Io;
 import Quickshell.Services.Pipewire;
 import QtQuick;
 
+/**
+ * Simple polled network state service.
+ */
 Singleton {
     id: root
 
diff --git a/.config/quickshell/services/Notifications.qml b/.config/quickshell/services/Notifications.qml
index 1b20a0fda..863a173e6 100644
--- a/.config/quickshell/services/Notifications.qml
+++ b/.config/quickshell/services/Notifications.qml
@@ -9,6 +9,12 @@ import Quickshell.Io
 import Quickshell.Services.Notifications
 import Qt.labs.platform
 
+/**
+ * Provides extra features not in Quickshell.Services.Notifications:
+ *  - Persistent storage
+ *  - Popup notifications, with timeout
+ *  - Notification groups by app
+ */
 Singleton {
 	id: root
     component Notif: QtObject {
diff --git a/.config/quickshell/services/PersistentStateManager.qml b/.config/quickshell/services/PersistentStateManager.qml
index 7c3fec739..a885d345e 100644
--- a/.config/quickshell/services/PersistentStateManager.qml
+++ b/.config/quickshell/services/PersistentStateManager.qml
@@ -9,6 +9,10 @@ import Quickshell.Io
 import Quickshell.Hyprland
 import Qt.labs.platform
 
+/**
+ * Manages persistent states across sessions.
+ * Run loadStates() once at startup to load the states, then use setState() and getState() to modify and access them.
+ */
 Singleton {
     id: root
     property string fileDir: XdgDirectories.state
diff --git a/.config/quickshell/services/ResourceUsage.qml b/.config/quickshell/services/ResourceUsage.qml
index b9d9ae20c..c9a501bc2 100644
--- a/.config/quickshell/services/ResourceUsage.qml
+++ b/.config/quickshell/services/ResourceUsage.qml
@@ -6,6 +6,9 @@ import QtQuick
 import Quickshell
 import Quickshell.Io
 
+/**
+ * Simple polled resource usage service with RAM, Swap, and CPU usage.
+ */
 Singleton {
 	property double memoryTotal: 1
 	property double memoryFree: 1
diff --git a/.config/quickshell/services/SystemInfo.qml b/.config/quickshell/services/SystemInfo.qml
index 8660693e8..ffd478b65 100644
--- a/.config/quickshell/services/SystemInfo.qml
+++ b/.config/quickshell/services/SystemInfo.qml
@@ -5,6 +5,9 @@ import QtQuick
 import Quickshell
 import Quickshell.Io
 
+/**
+ * Provides some system info: distro, username.
+ */
 Singleton {
     property string distroName: "Unknown"
     property string distroId: "unknown"
diff --git a/.config/quickshell/services/Todo.qml b/.config/quickshell/services/Todo.qml
index cbf5e02fe..f452a0178 100644
--- a/.config/quickshell/services/Todo.qml
+++ b/.config/quickshell/services/Todo.qml
@@ -7,6 +7,10 @@ import Quickshell.Io;
 import Qt.labs.platform
 import QtQuick;
 
+/**
+ * Simple to-do list manager.
+ * Each item is an object with "content" and "done" properties.
+ */
 Singleton {
     id: root
     property var filePath: `${XdgDirectories.state}/user/todo.json`