documentation for all JS files

static/js/contacts-filter.js

@@ -1,4 +1,21 @@
-// Debounce function
+/**
+ * @fileoverview Manages the contacts filtering functionality.
+ * This file handles:
+ * - Contact search with debounced input
+ * - Filter form submission
+ * - Search state persistence
+ * - Filter clearing functionality
+ */
+
+/**
+ * Creates a debounced version of a function that delays its execution
+ * until after a specified wait time has elapsed since the last time it was invoked.
+ * This helps prevent excessive form submissions during rapid user input.
+ * @function
+ * @param {Function} func - The function to debounce
+ * @param {number} wait - The number of milliseconds to delay (300ms default for search)
+ * @returns {Function} A debounced version of the provided function
+ */
 function debounce(func, wait) {
     let timeout;
     return function(...args) {
@@ -7,7 +24,14 @@ function debounce(func, wait) {
     };
 }
 
-// Initialize filter functionality
+/**
+ * Initializes the contacts filter functionality when the DOM is loaded.
+ * Sets up:
+ * - Auto-submit on select changes
+ * - Debounced search input with cursor position persistence
+ * - Filter clearing functionality
+ * @function
+ */
 document.addEventListener('DOMContentLoaded', function() {
     // Auto-submit the form on select change
     document.querySelectorAll('#filterForm select').forEach(function(el) {
@@ -41,7 +65,11 @@ document.addEventListener('DOMContentLoaded', function() {
         }
     }
 
-    // Clear button resets all filters and submits the form
+    /**
+     * Handles the clear filters button click.
+     * Resets all filter inputs and submits the form.
+     * @event
+     */
     document.getElementById('clearFilters').addEventListener('click', function() {
         document.querySelector('#filterForm input[name="search"]').value = '';
         document.querySelector('#filterForm select[name="role"]').selectedIndex = 0;