Merge pull request #139 from alamin655/JSDocs

:broom: chore: Enhance JS Code Documentation with Comprehensive Comments and Docstrings

Cargo.lock

@@ -2386,9 +2386,9 @@ dependencies = [
 
 [[package]]
 name = "regex"
-version = "1.9.0"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "89089e897c013b3deb627116ae56a6955a72b8bed395c9526af31c9fe528b484"
+checksum = "b2eae68fc220f7cf2532e4494aded17545fce192d59cd996e0fe7887f4ceb575"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -2398,9 +2398,9 @@ dependencies = [
 
 [[package]]
 name = "regex-automata"
-version = "0.3.0"
+version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fa250384981ea14565685dea16a9ccc4d1c541a13f82b9c168572264d1df8c56"
+checksum = "83d3daa6976cffb758ec878f108ba0e062a45b2d6ca3a2cca965338855476caf"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -2693,18 +2693,18 @@ checksum = "388a1df253eca08550bef6c72392cfe7c30914bf41df5269b68cbd6ff8f570a3"
 
 [[package]]
 name = "serde"
-version = "1.0.166"
+version = "1.0.168"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d01b7404f9d441d3ad40e6a636a7782c377d2abdbe4fa2440e2edcc2f4f10db8"
+checksum = "d614f89548720367ded108b3c843be93f3a341e22d5674ca0dd5cd57f34926af"
 dependencies = [
  "serde_derive",
 ]
 
 [[package]]
 name = "serde_derive"
-version = "1.0.166"
+version = "1.0.168"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5dd83d6dde2b6b2d466e14d9d1acce8816dedee94f735eac6395808b3483c6d6"
+checksum = "d4fe589678c688e44177da4f27152ee2d190757271dc7f1d5b6b9f68d869d641"
 dependencies = [
  "proc-macro2 1.0.63",
  "quote 1.0.29",
@@ -2994,18 +2994,18 @@ dependencies = [
 
 [[package]]
 name = "thiserror"
-version = "1.0.41"
+version = "1.0.43"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c16a64ba9387ef3fdae4f9c1a7f07a0997fce91985c0336f1ddc1822b3b37802"
+checksum = "a35fc5b8971143ca348fa6df4f024d4d55264f3468c71ad1c2f365b0a4d58c42"
 dependencies = [
  "thiserror-impl",
 ]
 
 [[package]]
 name = "thiserror-impl"
-version = "1.0.41"
+version = "1.0.43"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d14928354b01c4d6a4f0e549069adef399a284e7995c7ccca94e8a07a5346c59"
+checksum = "463fe12d7993d3b327787537ce8dd4dfa058de32fc2b195ef3cde03dc4771e8f"
 dependencies = [
  "proc-macro2 1.0.63",
  "quote 1.0.29",
@@ -3322,9 +3322,9 @@ checksum = "497961ef93d974e23eb6f433eb5fe1b7930b659f06d12dec6fc44a8f554c0bba"
 
 [[package]]
 name = "ucd-trie"
-version = "0.1.5"
+version = "0.1.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9e79c4d996edb816c91e4308506774452e55e95c3c9de07b6729e17e15a5ef81"
+checksum = "ed646292ffc8188ef8ea4d1e0e0150fb15a5c2e12ad9b8fc191ae7a8a7f3c4b9"
 
 [[package]]
 name = "unicase"
@@ -3543,7 +3543,7 @@ dependencies = [
 
 [[package]]
 name = "websurfx"
-version = "0.13.13"
+version = "0.13.16"
 dependencies = [
  "actix-files",
  "actix-web",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "websurfx"
-version = "0.13.13"
+version = "0.13.16"
 edition = "2021"
 description = "An open-source alternative to Searx that provides clean, ad-free, and organic results with incredible speed while keeping privacy and security in mind."
 repository = "https://github.com/neon-mmd/websurfx"

public/static/cookies.js

@@ -1,15 +1,26 @@
-// This function is executed when any page on the website finishes loading and
-// this function retrieves the cookies if it is present on the user's machine.
-// If it is available then the saved cookies is display in the cookies tab
-// otherwise an appropriate message is displayed if it is not available.
+/**
+ * This function is executed when any page on the website finishes loading and
+ * this function retrieves the cookies if it is present on the user's machine.
+ * If it is available then the saved cookies is display in the cookies tab
+ * otherwise an appropriate message is displayed if it is not available.
+ *
+ * @function
+ * @listens DOMContentLoaded
+ * @returns {void}
+ */
 document.addEventListener(
   'DOMContentLoaded',
   () => {
     try {
+      // Decode the cookie value
       let cookie = decodeURIComponent(document.cookie)
+      // Set the value of the input field to the decoded cookie value if it is not empty
+      // Otherwise, display a message indicating that no cookies have been saved on the user's system
       document.querySelector('.cookies input').value =
         cookie !== '' ? cookie : 'No cookies have been saved on your system'
     } catch (error) {
+      // If there is an error decoding the cookie, log the error to the console
+      // and display an error message in the input field
       console.error('Error decoding cookie:', error)
       document.querySelector('.cookies input').value = 'Error decoding cookie'
     }

public/static/pagination.js

@@ -1,5 +1,5 @@
 /**
- * Navigates to the next page by incrementing the current page number in the URL query parameters.
+ * Navigates to the next page by incrementing the current page number in the URL query string.
  * @returns {void}
  */
 function navigate_forward() {
@@ -19,7 +19,7 @@ function navigate_forward() {
 }
 
 /**
- * Navigates to the previous page by decrementing the current page number in the URL query parameters.
+ * Navigates to the previous page by decrementing the current page number in the URL query string.
  * @returns {void}
  */
 function navigate_backward() {

public/static/settings.js

@@ -1,5 +1,7 @@
-// This function handles the toggling of selections of all upstream search engines 
-// options in the settings page under the tab engines.
+/**
+ * This function handles the toggling of selections of all upstream search engines 
+ * options in the settings page under the tab engines.
+ */
 function toggleAllSelection() {
   document
     .querySelectorAll('.engine')
@@ -10,25 +12,36 @@ function toggleAllSelection() {
     )
 }
 
-// This function adds the functionality to sidebar buttons to only show settings 
-// related to that tab.
+/**
+ * This function adds the functionality to sidebar buttons to only show settings 
+ * related to that tab.
+ * @param {HTMLElement} current_tab - The current tab that was clicked.
+ */
 function setActiveTab(current_tab) {
+  // Remove the active class from all tabs and buttons
   document
     .querySelectorAll('.tab')
     .forEach((tab) => tab.classList.remove('active'))
   document
     .querySelectorAll('.btn')
     .forEach((tab) => tab.classList.remove('active'))
+
+  // Add the active class to the current tab and its corresponding settings
   current_tab.classList.add('active')
   document
     .querySelector(`.${current_tab.innerText.toLowerCase().replace(' ', '_')}`)
     .classList.add('active')
 }
 
-// This function adds the functionality to save all the user selected preferences
-// to be saved in a cookie on the users machine.
+/**
+ * This function adds the functionality to save all the user selected preferences
+ * to be saved in a cookie on the users machine.
+ */
 function setClientSettings() {
+  // Create an object to store the user's preferences
   let cookie_dictionary = new Object()
+
+  // Loop through all select tags and add their values to the cookie dictionary
   document.querySelectorAll('select').forEach((select_tag) => {
     if (select_tag.name === 'themes') {
       cookie_dictionary['theme'] = select_tag.value
@@ -36,6 +49,8 @@ function setClientSettings() {
       cookie_dictionary['colorscheme'] = select_tag.value
     }
   })
+
+  // Loop through all engine checkboxes and add their values to the cookie dictionary
   let engines = []
   document.querySelectorAll('.engine').forEach((engine_checkbox) => {
     if (engine_checkbox.checked === true) {
@@ -43,33 +58,44 @@ function setClientSettings() {
     }
   })
   cookie_dictionary['engines'] = engines
+
+  // Set the expiration date for the cookie to 1 year from the current date
   let expiration_date = new Date()
   expiration_date.setFullYear(expiration_date.getFullYear() + 1)
+
+  // Save the cookie to the user's machine
   document.cookie = `appCookie=${JSON.stringify(
     cookie_dictionary
   )}; expires=${expiration_date.toUTCString()}`
 
+  // Display a success message to the user
   document.querySelector('.message').innerText =
     '✅ The settings have been saved sucessfully!!'
 
+  // Clear the success message after 10 seconds
   setTimeout(() => {
     document.querySelector('.message').innerText = ''
   }, 10000)
 }
 
-// This functions gets the saved cookies if it is present on the user's machine If it 
-// is available then it is parsed and converted to an object which is then used to 
-// retrieve the preferences that the user had selected previously and is then loaded in the 
-// website otherwise the function does nothing and the default server side settings are loaded.
+/**
+ * This functions gets the saved cookies if it is present on the user's machine If it 
+ * is available then it is parsed and converted to an object which is then used to 
+ * retrieve the preferences that the user had selected previously and is then loaded in the 
+ * website otherwise the function does nothing and the default server side settings are loaded.
+ */
 function getClientSettings() {
+  // Get the appCookie from the user's machine
   let cookie = decodeURIComponent(document.cookie)
 
+  // If the cookie is not empty, parse it and use it to set the user's preferences
   if (cookie !== '') {
     let cookie_value = decodeURIComponent(document.cookie)
       .split(';')
       .map((item) => item.split('='))
       .reduce((acc, [_, v]) => (acc = JSON.parse(v)) && acc, {})
 
+    // Loop through all link tags and update their href values to match the user's preferences
     let links = Array.from(document.querySelectorAll('link')).forEach(
       (item) => {
         if (item.href.includes('static/themes')) {