Added docstrings to Calibration screen, and deleted redundant imports

[BinaryWiz4rd]

PR Type

Documentation

---

Description

• Added comprehensive JSDoc docstrings to all calibration module functions

• Documented global variables and their types throughout calibration system

• Removed redundant imports from display.js and faceModel.js files

• Enhanced code maintainability with detailed parameter and return type documentation

---

Diagram Walkthrough

flowchart LR
  A["Calibration Modules"] -->|Add JSDoc| B["Enhanced Documentation"]
  C["Redundant Imports"] -->|Remove| D["Cleaner Code"]
  B --> E["Better Maintainability"]
  D --> E

Loading

File Walkthrough

	Relevant files
Documentation	7 files index.js Added component-level JSDoc documentation                                +7/-0      calibration.js Added initCalibration function documentation                          +7/-0      distance.js Added JSDoc for distance calculation functions                      +18/-0    domRefs.js Added documentation for DOM reference management                  +9/-0      dotCalibration.js Added extensive JSDoc for calibration sequence functions  +54/-4    mathUtils.js Added JSDoc for matrix operation utility functions              +23/-0    video.js Added documentation for camera loop and stream management +14/-0
Documentation, dependencies	2 files display.js Removed redundant imports and added function docs                +8/-2      faceModel.js Removed redundant import and added model initialization docs +10/-1

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
🔴	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Broken JSDoc block: The new JSDoc for placeDot is malformed because the function declaration is appended to the comment terminator (*/export), undermining self-documentation and likely breaking JSDoc tooling/linting. Referred Code * Immediately positions the calibration dot element at specific pixel coordinates. * @param {number} x - Left offset in pixels. * @param {number} y - Top offset in pixels. * @param {boolean} [visible=true] - Whether the dot should be visible. */export function placeDot(x, y, visible = true) { refs.calDot.style.left = `${x}px`; Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Audit coverage unclear: The new documentation states calibration results are persisted to Firebase/Redux, but the diff does not show whether those potentially sensitive write actions are audit-logged with user ID, timestamp, action, and outcome. Referred Code /** * Calibration Component. * * This is the main view for the eye-tracking calibration process. * It manages the UI states (idle, success, failed), initializes the webcam and MediaPipe models via helper utilities, * verifies calibration accuracy against a threshold, and persists successful models to Firebase and Redux. */ Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Permission failure handling: Camera permission denial is surfaced via a modal/alert, but the diff does not show whether getUserMedia/model inference failures are consistently caught, logged, and handled with actionable context across the calibration flow. Referred Code /** * Requests camera permissions, initializes the video stream, and starts the processing loop. * Also manages UI state to show video elements and hide static previews. * @returns {Promise<void>} */ export async function startDistanceCheck() { if (runningCamera) return; runningCamera = true; refs.staticPreview.classList.remove("show-flex"); refs.staticPreview.style.display = "none"; refs.video.classList.add("show"); refs.canvas.classList.add("show"); refs.stopBtn.style.display = "inline-block"; refs.distanceOverlay.style.display = "flex"; if (refs.runCalibBtnOverlay) { refs.runCalibBtnOverlay.style.display = "none"; ... (clipped 21 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Landmark input assumptions: New documentation and logic assume specific landmark indices exist (e.g., lm[33], lm[263]), but the diff does not show validation/guards against malformed model outputs or unexpected landmark arrays. Referred Code * Computes the Euclidean distance between the left and right eye landmarks. * Used as a proxy for the user's physical distance from the camera. * * @param {Array} lm - The array of face landmarks from MediaPipe. * @returns {number} The hypotenuse distance between the two eye points. */ export function computeEyeDistance(lm) { const l = lm[33]; const r = lm[263]; return Math.hypot(l.x - r.x, l.y - r.y); Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Centralize state instead of using globals Refactor the calibration logic to use a centralized state object or class instead of relying on mutable global variables exported across modules. This will improve data flow clarity, robustness, and maintainability. Examples: src/views/Calibration/utils/modules/distance.js [7] export let distanceOK = false; src/views/Calibration/utils/modules/dotCalibration.js [12-27] export let gazeData = []; /** * The resulting calibration coefficients for left and right eyes after 'fitting'. * @type {Object} */ export let calibrationModel = { left: { coefX: [0,0,0,0,0,0], coefY: [0,0,0,0,0,0] }, right: { coefX: [0,0,0,0,0,0], coefY: [0,0,0,0,0,0] } }; ... (clipped 6 lines) Solution Walkthrough: Before: // distance.js export let distanceOK = false; export function handleDistanceState(landmarks) { // ... mutates distanceOK distanceOK = true; } // dotCalibration.js export let runningDot = false; export async function runDotCalibration(onComplete) { if (!distanceOK) return; // relies on global state runningDot = true; // ... } // video.js import { runningDot } from "./dotCalibration.js"; export function cameraLoop() { if (runningDot && !ok) showFsWarning(); // reads global state } After: // state.js export class CalibrationState { constructor() { this.distanceOK = false; this.runningDot = false; // ... other state variables } } // calibration.js import { CalibrationState } from "./state.js"; export async function initCalibration(onComplete) { const state = new CalibrationState(); // ... runDotCalibration(state, onComplete); } // dotCalibration.js export async function runDotCalibration(state, onComplete) { if (!state.distanceOK) return; state.runningDot = true; // ... } Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a major architectural flaw—the heavy use of mutable global state across modules—which severely impacts the maintainability and robustness of the entire calibration system.	High
General	Check least-squares results Add a null check for the results of leastSquares to prevent assigning an invalid model if the calculation fails. src/views/Calibration/utils/modules/display.js [29-33] ... const coeffsX = leastSquares(A, bx); const coeffsY = leastSquares(A, by); +if (!coeffsX || !coeffsY) { + return { success: false }; +} calibrationModel[eye].coefX = coeffsX; calibrationModel[eye].coefY = coeffsY; ... [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies that leastSquares can return null and adds a necessary check to prevent assigning null to the model, which would cause runtime errors. This improves the robustness of the calibration logic.	Medium
Possible issue	Fix JSDoc/export syntax Add a newline between the JSDoc closing delimiter and the export keyword for the placeDot function to fix a syntax error. src/views/Calibration/utils/modules/dotCalibration.js [81-85] -... -*/export function placeDot(x, y, visible = true) { +... +*/ +export function placeDot(x, y, visible = true) { refs.calDot.style.left = `${x}px`; refs.calDot.style.top = `${y}px`; refs.calDot.style.opacity = visible ? "1" : "0"; } [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 3 __ Why: The suggestion correctly identifies a formatting error where a JSDoc comment is on the same line as the function export, which can break documentation tools. It's a minor code style improvement.	Low
More