Add JSDoc documentation and file headers to all source files

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

src/module/sortNumEngZhtw.js

@@ -1,43 +1,52 @@
+// 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 sortNumEngZhtw Sorting for mixed numeric/text data. */
+
 /**
- * 數字、英文、中文，排序
- * @param {array} data List
- * @returns
+ * Sorts an array of mixed numeric and text values in place.
+ *
+ * Numbers come first (ascending), followed by text sorted by
+ * Traditional Chinese locale (zh-Hant-TW).
+ *
+ * @param {Array<string|number>} data - The array to sort.
+ * @returns {Array<string|number>} The sorted array (same reference).
  */
 export function sortNumEngZhtw(data) {
   return data.sort((a, b) => {
-    // 檢查兩個值是否都是數字
     const isANumber = !isNaN(parseFloat(a)) && isFinite(a);
     const isBNumber = !isNaN(parseFloat(b)) && isFinite(b);
 
-    // 如果兩個值都是數字，直接比較大小
     if (isANumber && isBNumber) return parseFloat(a) - parseFloat(b);
 
-    // 如果其中一個值是數字，將數字視為最小，排在前面
     if (isANumber) return -1;
     if (isBNumber) return 1;
 
-    // 其他情況下，使用 localeCompare 方法進行中文排序
     return a.localeCompare(b, 'zh-Hant-TW', { sensitivity: 'accent' });
   });
 }
+
 /**
- * 數字、英文、中文，給 Filter Table 排序
- * @param {string} a label
- * @param {string} b label
- * @returns
+ * Comparator function for sorting mixed numeric and text values.
+ *
+ * Suitable for use as an Array.sort() callback. Numbers sort before
+ * text, and text is sorted by Traditional Chinese locale.
+ *
+ * @param {string|number} a - First value to compare.
+ * @param {string|number} b - Second value to compare.
+ * @returns {number} Negative if a < b, positive if a > b, zero if equal.
  */
 export function sortNumEngZhtwForFilter(a, b) {
-  // 檢查兩個值是否都是數字
   const isANumber = !isNaN(parseFloat(a)) && isFinite(a);
   const isBNumber = !isNaN(parseFloat(b)) && isFinite(b);
 
-  // 如果兩個值都是數字，直接比較大小
   if (isANumber && isBNumber) return parseFloat(a) - parseFloat(b);
 
-  // 如果其中一個值是數字，將數字視為最小，排在前面
   if (isANumber) return -1;
   if (isBNumber) return 1;
 
-  // 其他情況下，使用 localeCompare 方法進行中文排序
   return a.localeCompare(b, 'zh-Hant-TW', { sensitivity: 'accent' });
 }