Add JSDoc documentation and file headers to all source files

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

src/views/Discover/Performance/FreqChart.vue

@@ -3,6 +3,17 @@
 </template>
 
 <script setup>
+// The Lucia project.
+// Copyright 2024-2026 DSP, inc.  All rights reserved.
+// Authors:
+//   cindy.chang@dsp.im (Cindy Chang), 2024/5/30
+//   imacat.yang@dsp.im (imacat), 2023/9/23
+/**
+ * @module views/Discover/Performance/FreqChart
+ *   Frequency chart component displaying activity
+ *   occurrence data with Chart.js bar charts.
+ */
+
 import { ref, onMounted } from 'vue';
 import {
   setTimeStringFormatBaseOnTimeDifference,
@@ -126,8 +137,8 @@ const customizeScaleChartOptionTicks = (scaleObjectToAlter, ticksOfXAxis) => {
 };
 
 /** Compare page and Performance have this same function.
- * 在一個基本的物件上加以客製化這個物件，客製化的參照來源是 content 的內容
- * 之所以有辦法這樣撰寫，是因為我們知道物件的順序是先 x 再 title 再 text
+ * Customizes a base tooltip object using the content data.
+ * The object order is known to be: x, then title, then text.
  * This function alters the title property of known scales object of Chart option
  * This is based on the fact that we know the order must be x -> title -> text.
  * @param {object} whichScaleObj PrimeVue scale option object to reference to
@@ -160,6 +171,12 @@ const customizeScaleChartOptionTitleByContent = (whichScaleObj, content) => {
     };
 };
 
+/**
+ * Builds the PrimeVue line chart data and options configuration.
+ * @param {object} chartData - The chart data from the API.
+ * @param {object} content - The axis label content.
+ * @param {string} pageName - 'Compare' or page identifier.
+ */
 const getLineChartPrimeVueSetting = (chartData, content, pageName) => {
   let datasetsArr;
   let datasets;

src/views/Discover/Performance/index.vue

@@ -136,6 +136,18 @@
   </main>
 </template>
 <script>
+// The Lucia project.
+// Copyright 2024-2026 DSP, inc.  All rights reserved.
+// Authors:
+//   chiayin.kuo@dsp.im (chiayin), 2023/1/31
+//   cindy.chang@dsp.im (Cindy Chang), 2024/5/30
+//   imacat.yang@dsp.im (imacat), 2023/9/23
+/**
+ * @module views/Discover/Performance
+ *   Performance analysis page with activity duration
+ *   charts, frequency data, and statistical summaries.
+ */
+
 import { useConformanceStore } from '@/stores/conformance';
 
 export default {
@@ -247,6 +259,10 @@ const avgWaitingTimeByEdgeHeight = ref(500);
 const casesByTaskHeight = ref(500);
 
 // Methods
+/**
+ * Scrolls to the selected chart section.
+ * @param {string} tagId - The anchor tag ID to navigate to.
+ */
 function handleClick(tagId) {
   isActive.value = tagId;
 
@@ -257,11 +273,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();
@@ -275,6 +301,11 @@ function setXLabelsData(valueData) {
   return data;
 }
 
+/**
+ * Calculates the height for a horizontal bar chart based on bar count.
+ * @param {object} chartData - The chart data.
+ * @returns {string} The CSS height string.
+ */
 function getHorizontalBarHeight(chartData) {
   const totalBars = chartData.data.length;
   let hBarHeight = horizontalBarHeight;
@@ -284,6 +315,12 @@ function getHorizontalBarHeight(chartData) {
   return hBarHeight + 'px'
 }
 
+/**
+ * Builds a bar chart configuration for Chart.js.
+ * @param {object} chartData - The chart data from the API.
+ * @param {object} content - The axis label content.
+ * @returns {Array} [chartData, chartOptions] tuple.
+ */
 function getBarChart(chartData, content) {
   const getMoment = (time)=> moment(time).format('YYYY/M/D hh:mm:ss');
   let primeVueSetData = {};
@@ -390,6 +427,14 @@ function getBarChart(chartData, content) {
   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;
@@ -526,6 +571,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,
@@ -537,6 +588,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;
@@ -561,6 +618,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,
@@ -576,6 +639,13 @@ function customizeScaleChartOptionTicks(scaleObjectToAlter, ticksOfXAxis) {
   };
 }
 
+/**
+ * Builds a line chart with explicit scale declarations.
+ * @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 getExplicitDeclaredLineChart(chartData, content, yUnit) {
   const minX = chartData.x_axis.min;
   const maxX = chartData.x_axis.max;
@@ -699,6 +769,13 @@ function getExplicitDeclaredLineChart(chartData, content, yUnit) {
   return [primeVueSetData, primeVueSetOption]
 }
 
+/**
+ * Builds a line chart for average waiting time data.
+ * @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 getAvgWaitingTimeLineChart(chartData, content, yUnit) {
   const getMoment = (time)=> moment(time).format('YYYY/M/D hh:mm:ss');
   const minX = chartData.x_axis.min;