documentation for all JS files

static/js/conversation.js

@@ -1,4 +1,23 @@
-// Initialize chat when document is ready
+/**
+ * @fileoverview Manages the real-time conversation functionality.
+ * This file handles:
+ * - Chat message display and management
+ * - Message submission with file attachments
+ * - Real-time message updates
+ * - Chat state management
+ * - UI interactions and animations
+ */
+
+/**
+ * Initializes the chat functionality when the document is ready.
+ * Sets up:
+ * - Chat state and message tracking
+ * - Message display and submission
+ * - File attachment handling
+ * - Real-time message updates
+ * - Cleanup on page unload
+ * @function
+ */
 $(document).ready(function() {
     const conversationId = window.conversationId; // Set this in the template
     const currentUserId = window.currentUserId; // Set this in the template
@@ -10,7 +29,19 @@ $(document).ready(function() {
     // Keep track of messages we've already displayed
     const displayedMessageIds = new Set();
 
-    // Function to append a new message to the chat
+    /**
+     * Appends a new message to the chat interface.
+     * Handles message formatting, attachments, and UI updates.
+     * @function
+     * @param {Object} message - The message object to append
+     * @param {string} message.id - The unique message ID
+     * @param {string} message.content - The message content
+     * @param {string} message.sender_id - The ID of the message sender
+     * @param {string} message.sender_name - The name of the message sender
+     * @param {string} message.sender_avatar - The avatar URL of the sender
+     * @param {string} message.created_at - The message creation timestamp
+     * @param {Array} [message.attachments] - Array of file attachments
+     */
     function appendMessage(message) {
         console.log('[Conversation] Attempting to append message:', {
             messageId: message.id,
@@ -79,14 +110,23 @@ $(document).ready(function() {
         }
     });
 
-    // Scroll to bottom of chat messages
+    /**
+     * Scrolls the chat window to the bottom.
+     * @function
+     */
     function scrollToBottom() {
         const chatMessages = document.getElementById('chatMessages');
         chatMessages.scrollTop = chatMessages.scrollHeight;
     }
     scrollToBottom();
 
-    // Listen for new messages
+    /**
+     * Event handler for new messages.
+     * Appends new messages to the chat when received.
+     * @event
+     * @param {Event} event - The event object
+     * @param {Object} message - The new message object
+     */
     $(document).on('new_message', function(event, message) {
         console.log('[Conversation] Received new_message event:', {
             messageId: message.id,
@@ -96,7 +136,11 @@ $(document).ready(function() {
         appendMessage(message);
     });
 
-    // Handle file selection
+    /**
+     * Handles file selection for message attachments.
+     * Updates the UI to show selected files.
+     * @event
+     */
     $('#fileInput').on('change', function() {
         const files = Array.from(this.files);
         if (files.length > 0) {
@@ -107,7 +151,14 @@ $(document).ready(function() {
         }
     });
 
-    // Handle message form submission
+    /**
+     * Handles message form submission.
+     * Processes text messages and file attachments.
+     * Manages submission state and UI feedback.
+     * @event
+     * @param {Event} e - The form submission event
+     * @returns {boolean} false to prevent default form submission
+     */
     let isSubmitting = false;
     $('#messageForm').off('submit').on('submit', function(e) {
         e.preventDefault();
@@ -202,7 +253,10 @@ $(document).ready(function() {
         return false;
     });
 
-    // Clean up on page unload
+    /**
+     * Cleans up chat resources when the page is unloaded.
+     * @event
+     */
     $(window).on('beforeunload', function() {
         console.log('[Conversation] Cleaning up on page unload');
         chat.cleanup();