Add JSDoc documentation and file headers to all source files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/views/Compare/Dashboard/Compare.vue

@@ -150,6 +150,16 @@
   </main>
 </template>
 <script setup>
+// The Lucia project.
+// Copyright 2024-2026 DSP, inc.  All rights reserved.
+// Authors:
+//   cindy.chang@dsp.im (Cindy Chang), 2024/5/30
+/**
+ * @module views/Compare/Dashboard/Compare
+ *   Performance comparison dashboard with side-by-side
+ *   charts comparing two datasets.
+ */
+
 import { ref, onMounted } from 'vue';
 import { useRoute } from 'vue-router';
 import { storeToRefs } from 'pinia';
@@ -253,6 +263,10 @@ const colorSecondary = '#FFAA44';
 const sidebarState = ref(false);
 
 // Methods
+/**
+ * Scrolls to the selected chart section.
+ * @param {string} tagId - The anchor tag ID to navigate to.
+ */
 function handleClick(tagId) {
   isActive.value = tagId;
 
@@ -263,11 +277,21 @@ function handleClick(tagId) {
   }
 }
 
+/**
+ * Validates that a tag ID is safe for navigation.
+ * @param {string} tagId - The tag ID to validate.
+ * @returns {boolean} True if the tag ID is safe.
+ */
 function isSafeTagId(tagId) {
   const pattern = /^#?[a-zA-Z0-9]*$/;
   return pattern.test(tagId);
 }
 
+/**
+ * Generates evenly-spaced X-axis label timestamps.
+ * @param {object} valueData - Object with min and max date strings.
+ * @returns {Array<number>} Array of timestamp values.
+ */
 function setXLabelsData(valueData) {
   const min = new Date(valueData.min).getTime();
   const max = new Date(valueData.max).getTime();
@@ -281,6 +305,11 @@ function setXLabelsData(valueData) {
   return data;
 }
 
+/**
+ * Calculates the height for a horizontal bar chart based on bar count.
+ * @param {object} chartData - The chart data with x_axis labels.
+ * @returns {string} The CSS height string.
+ */
 function getHorizontalBarHeight(chartData) {
   const totalBars = chartData.x_axis.labels.length;
   let hBarHeight = horizontalBarHeight;
@@ -292,6 +321,13 @@ function getHorizontalBarHeight(chartData) {
   return hBarHeight + 'px'
 }
 
+/**
+ * Builds a line chart configuration for Chart.js.
+ * @param {object} chartData - The chart data from the API.
+ * @param {object} content - The axis label content.
+ * @param {string} yUnit - 'date' or 'count'.
+ * @returns {Array} [chartData, chartOptions] tuple.
+ */
 function getLineChart(chartData, content, yUnit) {
   let datasetsPrimary;
   let datasetsSecondary;
@@ -415,6 +451,13 @@ function getLineChart(chartData, content, yUnit) {
   return [primeVueSetData, primeVueSetOption];
 }
 
+/**
+ * Builds a bar chart configuration for Chart.js.
+ * @param {object} chartData - The chart data from the API.
+ * @param {object} content - The axis label content.
+ * @param {string} caller - Identifier for chart-specific options.
+ * @returns {Array} [chartData, chartOptions] tuple.
+ */
 function getBarChart(chartData, content, caller) {
   const getMoment = (time)=> moment(time).format('YYYY/MM/DD');
   const labelPrimary = chartData.data[0].label;
@@ -514,6 +557,14 @@ function getBarChart(chartData, content, caller) {
   return [primeVueSetData, primeVueSetOption]
 }
 
+/**
+ * Builds a horizontal bar chart configuration for Chart.js.
+ * @param {object} chartData - The chart data from the API.
+ * @param {object} content - The axis label content.
+ * @param {boolean} isSingle - Whether labels are single values.
+ * @param {string} xUnit - 'date' or 'count'.
+ * @returns {Array} [chartData, chartOptions] tuple.
+ */
 function getHorizontalBarChart(chartData, content, isSingle, xUnit) {
   const maxY = chartData.y_axis.max;
   const getSimpleTimeLabel = simpleTimeLabel;
@@ -633,6 +684,12 @@ function getHorizontalBarChart(chartData, content, isSingle, xUnit) {
   return [primeVueSetData, primeVueSetOption]
 }
 
+/**
+ * Customizes Chart.js scale options with content and tick data.
+ * @param {object} whichScaleObj - The base scale options object.
+ * @param {object} options - Options containing content and ticksOfXAxis.
+ * @returns {object} The customized scale options.
+ */
 function getCustomizedScaleOption(whichScaleObj, {customizeOptions: {
       content,
       ticksOfXAxis,
@@ -644,6 +701,12 @@ function getCustomizedScaleOption(whichScaleObj, {customizeOptions: {
   return resultScaleObj;
 }
 
+/**
+ * Sets axis titles on a scale options object.
+ * @param {object} whichScaleObj - The base scale options.
+ * @param {object} content - Object with x and y axis title text.
+ * @returns {object} The scale options with updated titles.
+ */
 function customizeScaleChartOptionTitleByContent(whichScaleObj, content){
   if (!content) {
     return whichScaleObj;
@@ -668,6 +731,12 @@ function customizeScaleChartOptionTitleByContent(whichScaleObj, content){
     };
 }
 
+/**
+ * Sets custom tick callbacks on a scale options object.
+ * @param {object} scaleObjectToAlter - The scale options to modify.
+ * @param {Array} ticksOfXAxis - The formatted tick labels.
+ * @returns {object} The scale options with custom ticks.
+ */
 function customizeScaleChartOptionTicks(scaleObjectToAlter, ticksOfXAxis) {
   return {
     ...scaleObjectToAlter,
@@ -683,6 +752,13 @@ function customizeScaleChartOptionTicks(scaleObjectToAlter, ticksOfXAxis) {
   };
 }
 
+/**
+ * Builds an alternative line chart configuration with inline scales.
+ * @param {object} chartData - The chart data from the API.
+ * @param {object} content - The axis label content.
+ * @param {string} yUnit - 'date' or 'count'.
+ * @returns {Array} [chartData, chartOptions] tuple.
+ */
 function getLineChart0(chartData, content, yUnit) {
   let datasetsPrimary;
   let datasetsSecondary;
@@ -836,6 +912,14 @@ function getLineChart0(chartData, content, yUnit) {
   return [primeVueSetData, primeVueSetOption];
 }
 
+/**
+ * Builds a horizontal bar chart for cases-by-task data.
+ * @param {object} chartData - The chart data from the API.
+ * @param {object} content - The axis label content.
+ * @param {boolean} isSingle - Whether labels are single values.
+ * @param {string} [xUnit='count'] - The x-axis unit.
+ * @returns {Array} [chartData, chartOptions] tuple.
+ */
 function getCaseByTaskHorizontalBarChart(chartData, content, isSingle, xUnit = 'count') {
   const labelPrimary = chartData.data[0].label;
   const labelSecondary = chartData.data[1].label;
@@ -990,6 +1074,14 @@ function getCaseByTaskHorizontalBarChart(chartData, content, isSingle, xUnit = '
   return [primeVueSetData, primeVueSetOption]
 }
 
+/**
+ * Builds a horizontal bar chart for average process time data.
+ * @param {object} chartData - The chart data from the API.
+ * @param {object} content - The axis label content.
+ * @param {boolean} isSingle - Whether labels are single values.
+ * @param {string} [xUnit='date'] - The x-axis unit.
+ * @returns {Array} [chartData, chartOptions] tuple.
+ */
 function getAvgProcessTimeHorizontalBarChart(chartData, content, isSingle, xUnit="date") {
   const maxY = chartData.y_axis.max;
   const getSimpleTimeLabel = simpleTimeLabel;