Add JSDoc documentation and file headers to all source files

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

src/module/setChartData.js

@@ -1,14 +1,27 @@
+// The Lucia project.
+// Copyright 2023-2026 DSP, inc.  All rights reserved.
+// Authors:
+//   chiayin.kuo@dsp.im (chiayin), 2023/1/31
+//   imacat.yang@dsp.im (imacat), 2023/9/23
+//   cindy.chang@dsp.im (Cindy Chang), 2024/5/30
+/** @module setChartData Chart.js data transformation utilities. */
+
 import getMoment from 'moment';
 
 /**
- * 將後端的 chart data 加入最大、最小值，折線圖
- * @param   {array} baseData 後端給的 10 個時間點
- * @param   {number} xMax 2022-05-23T18:00:00
- * @param   {number} xMin 2022-05-23T08:00:00
- * @param   {boolean} isPercent 是否以百分比顯示
- * @param   {number} yMax case
- * @param   {number} yMin case
- * @returns {array} 可直接套入 chart.js 的 data
+ * Extends backend chart data with extrapolated boundary points for
+ * line charts. Prepends a calculated minimum and appends a calculated
+ * maximum data point based on linear extrapolation.
+ *
+ * @param {Array<{x: number, y: number}>} baseData - The 10 data points
+ *   from the backend.
+ * @param {number} xMax - The maximum x-axis timestamp.
+ * @param {number} xMin - The minimum x-axis timestamp.
+ * @param {boolean} isPercent - Whether values are percentages (0-1 range).
+ * @param {number} yMax - The maximum y-axis value for clamping.
+ * @param {number} yMin - The minimum y-axis value for clamping.
+ * @returns {Array<{x: number, y: number}>} The extended data array
+ *   with boundary points.
  */
 export function setLineChartData(baseData, xMax, xMin, isPercent, yMax, yMin) {
    // 將 baseData 轉換為包含 x 和 y 屬性的物件陣列
@@ -35,11 +48,14 @@ export function setLineChartData(baseData, xMax, xMin, isPercent, yMax, yMin) {
    return data;
  };
  /**
- * 計算 y 軸最小值
- * 
- * x 值為 0 ~ 11,
- * 將三的座標(ax, ay), (bx, by), (cx, cy)命名為 (a, b), (c, d), (e, f)
- * 最小值: (f - b)(c - a) = (e - a)(d - b)，求 b = (ed - ad - fa - fc) / (e - c - a)
+ * Extrapolates the Y-axis minimum boundary value using linear
+ * interpolation from the first two data points.
+ *
+ * @param {Array<{x: number, y: number}>} baseData - The base data points.
+ * @param {boolean} isPercent - Whether to clamp to 0-1 range.
+ * @param {number} yMin - The minimum allowed Y value.
+ * @param {number} yMax - The maximum allowed Y value.
+ * @returns {number} The extrapolated and clamped Y minimum value.
  */
 function calculateYMin(baseData, isPercent, yMin, yMax) {
   let a = 0;
@@ -51,11 +67,14 @@ function calculateYMin(baseData, isPercent, yMin, yMax) {
   return clampValue(b, isPercent, yMin, yMax);
 };
 /**
- * 計算 y 軸最大值
- * 
- * x 值為 9 ~ 11,
- * 將三的座標(ax, ay), (bx, by), (cx, cy)命名為 (a, b), (c, d), (e, f)
- * 最大值: (f - b)(e - c) = (f - d)(e - a)，求 f = (be - bc -de + da) / (a - c)
+ * Extrapolates the Y-axis maximum boundary value using linear
+ * interpolation from the last two data points.
+ *
+ * @param {Array<{x: number, y: number}>} baseData - The base data points.
+ * @param {boolean} isPercent - Whether to clamp to 0-1 range.
+ * @param {number} yMin - The minimum allowed Y value.
+ * @param {number} yMax - The maximum allowed Y value.
+ * @returns {number} The extrapolated and clamped Y maximum value.
  */
 function calculateYMax(baseData, isPercent, yMin, yMax) {
   let ma = 9;
@@ -67,15 +86,14 @@ function calculateYMax(baseData, isPercent, yMin, yMax) {
   return clampValue(mf, isPercent, yMin, yMax);
 };
 /**
- * 將值限制在指定範圍內
- * 如果 isPercent 為 true，則將值限制在 0 到 1 之間
- * 否則，將值限制在 yMin 和 yMax 之間
- * 
- * @param {number} value 需要被限制的值
- * @param {boolean} isPercent 如果為 true，表示值應該被限制在百分比範圍內（0 到 1）
- * @param {number} min 非百分比情況下的最小允許值（yMin）
- * @param {number} max 非百分比情況下的最大允許值（yMax）
- * @returns {number} 被限制在指定範圍內的值
+ * Clamps a value within a specified range. If isPercent is true, the
+ * value is clamped to [0, 1]; otherwise to [min, max].
+ *
+ * @param {number} value - The value to clamp.
+ * @param {boolean} isPercent - Whether to use the percentage range [0, 1].
+ * @param {number} min - The minimum bound (used when isPercent is false).
+ * @param {number} max - The maximum bound (used when isPercent is false).
+ * @returns {number} The clamped value.
  */
 function clampValue(value, isPercent, min, max) {
   if (isPercent) {
@@ -95,9 +113,13 @@ function clampValue(value, isPercent, min, max) {
   return value;
 };
 /**
- * 將後端的 chart data x 值轉換時間格式，長條圖
- * @param   {array} baseData 後端給的 10 個時間點
- * @returns {array} 可直接套入 chart.js 的 data
+ * Converts backend chart data timestamps to formatted date strings
+ * for bar charts.
+ *
+ * @param {Array<{x: string, y: number}>} baseData - The data points from
+ *   the backend with ISO timestamp x values.
+ * @returns {Array<{x: string, y: number}>} Data with x values formatted
+ *   as "YYYY/M/D hh:mm:ss".
  */
 export function setBarChartData(baseData) {
   let data = baseData.map(i =>{
@@ -109,11 +131,13 @@ export function setBarChartData(baseData) {
   return data
 };
 /**
- * 將一段時間均分成多段的時間點
- * @param   {string} startTime 開始時間(ex: 434) 總秒數
- * @param   {string} endTime   結束時間(ex: 259065) 總秒數
- * @param   {number} amount    切分成多少段
- * @returns {array}            均分成多段的時間 array
+ * Divides a time range into evenly spaced time points.
+ *
+ * @param {number} minTime - The start time in seconds.
+ * @param {number} maxTime - The end time in seconds.
+ * @param {number} amount - The number of time points to generate.
+ * @returns {Array<number>} An array of evenly spaced, rounded time
+ *   values in seconds.
  */
 export function timeRange(minTime, maxTime, amount) {
   // x 軸(時間軸)的範圍是最大-最小，從最小值按照 index 累加間距到最大值
@@ -129,11 +153,13 @@ export function timeRange(minTime, maxTime, amount) {
   return timeRange;
 };
 /**
- * 將 y 軸的值分割成跟 x 時間軸一樣的等份，使用統計學 R 語言算出貝茲曲線攻勢
- * @param   {array}  data       切分成多少段
- * @param   {number} yAmount    切分成多少段
- * @param   {number} yMax       y 最大值
- * @returns {array}             均分成多段的時間 array
+ * Generates smooth Y-axis values using cubic Bezier interpolation
+ * to produce evenly spaced ticks matching the X-axis divisions.
+ *
+ * @param {Array<{x: number, y: number}>} data - The source data points.
+ * @param {number} yAmount - The desired number of Y-axis ticks.
+ * @param {number} yMax - The maximum Y value (unused, kept for API).
+ * @returns {Array<number>} An array of interpolated Y values.
  */
 export function yTimeRange(data, yAmount, yMax) {
   const yRange = [];
@@ -171,10 +197,11 @@ export function yTimeRange(data, yAmount, yMax) {
   return yRange;
 };
 /**
- * 找出選擇的時間點的 index
- * @param {array} data xVal
- * @param {number} xValue x 值
- * @returns {numver} x index
+ * Finds the index of the closest value in an array to the given target.
+ *
+ * @param {Array<number>} data - The array of values to search.
+ * @param {number} xValue - The target value to find the closest match for.
+ * @returns {number} The index of the closest value in the array.
  */
 export function getXIndex(data, xValue) {
   let closestIndex = xValue; // 假定第一个元素的索引是 0
@@ -192,9 +219,11 @@ export function getXIndex(data, xValue) {
   return closestIndex;
 };
 /**
- * 有 dhms 表達的時間單位
- * @param {number} seconds 總秒數
- * @returns {string}
+ * Formats a duration in seconds to a compact string with d/h/m/s units.
+ *
+ * @param {number} seconds - The total number of seconds.
+ * @returns {string|null} The formatted string (e.g. "2d3h15m30s"),
+ *   or null if the input is NaN.
  */
 export function formatTime(seconds) {
   if(!isNaN(seconds)) {
@@ -221,9 +250,10 @@ export function formatTime(seconds) {
   }
 }
 /**
- * 只顯示最大的兩個單位
- * @param {array} times 時間
- * @returns {array}
+ * Truncates each time string to show only the two largest time units.
+ *
+ * @param {Array<string>} times - Array of duration strings (e.g. "2d3h15m30s").
+ * @returns {Array<string>} Array of truncated strings (e.g. "2d 3h").
  */
 export function formatMaxTwo(times) {
   const formattedTimes = [];