Adds JSDoc Typing to some of the JavaScript Files (#1307)

.config/quickshell/modules/common/functions/file_utils.js

@@ -1,3 +1,8 @@
+/**
+ * Trims the File protocol off the input string
+ * @param {string} str
+ * @returns {string}
+ */
 function trimFileProtocol(str) {
     return str.startsWith("file://") ? str.slice(7) : str;
 }

.config/quickshell/modules/common/functions/icons.js

@@ -1,5 +1,8 @@
 .pragma library
 
+/**
+ * @type {{[key: string]: string}}
+ */
 const substitutions = {
     "code-url-handler": "visual-studio-code",
     "Code": "visual-studio-code",
@@ -13,6 +16,10 @@ const substitutions = {
     "zen": "zen-browser",
     "": "image-missing"
 }
+
+/**
+ * @type {{[key: string]: string}}
+ */
 const regexSubstitutions = [
     {
         "regex": "/^steam_app_(\\d+)$/",
@@ -20,11 +27,18 @@ const regexSubstitutions = [
     }
 ]
 
-
+/**
+ * @param { string } iconName 
+ * @returns { boolean }
+ */
 function iconExists(iconName) {
     return false; // TODO: Make this work without Gtk
 }
 
+/**
+ * @param { string } str 
+ * @returns { string }
+ */
 function substitute(str) {
     // Normal substitutions
     if (substitutions[str])
@@ -47,6 +61,10 @@ function substitute(str) {
     return str;
 }
 
+/**
+ * @param { string | undefined } str 
+ * @returns { string } 
+ */
 function noKnowledgeIconGuess(str) {
     if (!str) return "image-missing";
 

.config/quickshell/modules/common/functions/string_utils.js

@@ -1,19 +1,40 @@
+/**
+ * Formats a string according to the args that are passed in
+ * @param { string } str 
+ * @param  {...any} args 
+ * @returns 
+ */
 function format(str, ...args) {
     return str.replace(/{(\d+)}/g, (match, index) =>
         typeof args[index] !== 'undefined' ? args[index] : match
     );
 }
 
+/**
+ * Returns the domain of the passed in url or null
+ * @param { string } url 
+ * @returns { string| null } 
+ */
 function getDomain(url) {
     const match = url.match(/^(?:https?:\/\/)?(?:www\.)?([^\/]+)/);
     return match ? match[1] : null;
 }
 
+/**
+ * Returns the base url of the passed in url or null
+ * @param { string } url 
+ * @returns { string | null } 
+ */
 function getBaseUrl(url) {
     const match = url.match(/^(https?:\/\/[^\/]+)(\/.*)?$/);
     return match ? match[1] : null;
 }
 
+/**
+ * Escapes single quotes in shell commands
+ * @param { string } str 
+ * @returns { string }
+ */
 function shellSingleQuoteEscape(str) {
     //  escape single quotes
     return String(str)
@@ -21,8 +42,15 @@ function shellSingleQuoteEscape(str) {
         .replace(/'/g, "'\\''");
 }
 
+/**
+ * Splits markdown blocks into three different types: text, think, and code.
+ * @param { string } markdown 
+ */
 function splitMarkdownBlocks(markdown) {
     const regex = /```(\w+)?\n([\s\S]*?)```|<think>([\s\S]*?)<\/think>/g;
+    /**
+     * @type {{type: "text" | "think" | "code"; content: string; lang: string | undefined; completed: boolean | undefined}[]}
+     */
     let result = [];
     let lastIndex = 0;
     let match;
@@ -89,10 +117,21 @@ function splitMarkdownBlocks(markdown) {
     return result;
 }
 
+/**
+ * Returns the original string with backslashes escaped
+ * @param { string } str 
+ * @returns { string }
+ */
 function escapeBackslashes(str) {
     return str.replace(/\\/g, '\\\\');
 }
 
+/**
+ * Wraps words to supplied maximum length
+ * @param { string | null } str 
+ * @param { number } maxLen 
+ * @returns { string }
+ */
 function wordWrap(str, maxLen) {
     if (!str) return "";
     let words = str.split(" ");

.config/quickshell/modules/common/widgets/notification_utils.js

@@ -1,5 +1,8 @@
 
-
+/**
+ * @param { string } summary 
+ * @returns { string }
+ */
 function findSuitableMaterialSymbol(summary = "") {
     const defaultType = 'chat';
     if(summary.length === 0) return defaultType;
@@ -49,6 +52,10 @@ function findSuitableMaterialSymbol(summary = "") {
 //         return messageTime.format(userOptions.time.dateFormat);
 // }
 
+/**
+ * @param { number | string | Date } timestamp 
+ * @returns { string }
+ */
 const getFriendlyNotifTimeString = (timestamp) => {
     const messageTime = new Date(timestamp);
     const now = new Date();