docs(calculate-version): 補齊 function JSDoc 與指令檔逐行註解並重建 README

app/version.js

@@ -8,6 +8,8 @@ const SEGMENT_LIMIT = 10;
  * @param {number[]} a - 第一個版本號區段陣列，例如 [1, 2, 3]。
  * @param {number[]} b - 第二個版本號區段陣列，例如 [1, 2, 0]。
  * @returns {number} 大於 0 表示 a 大於 b；小於 0 表示 a 小於 b；0 表示兩者相等。
+ *   相異區段回傳的是該段差值（非固定 ±1）。
+ * @throws {TypeError} 當 a 或 b 非陣列（無 length 屬性）時拋出。
  */
 function compareVersionArrays(a, b) {
     const length = Math.max(a.length, b.length);
@@ -70,6 +72,8 @@ function latestStableVersion(releases) {
  * 依最新穩定版字串計算下一個發行版本號：patch 加 1，patch 達 10 進位至 minor，minor 達 10 進位至 major。
  * @param {string} latest - 最新穩定版版本號字串，例如 "1.2.9"。
  * @returns {string} 下一個發行版本號字串，格式為 "major.minor.patch"，例如 "1.3.0"。
+ * @remarks 「逢 10 進位」為本專案自訂約定（非標準 SemVer）；輸入會先 String() 轉字串，
+ *   缺段或非數字段一律補 0（如 null/undefined → "0.0.1"），major 無進位上限。
  */
 function nextReleaseVersion(latest) {
     const parts = String(latest).split('.').map((part) => Number(part) || 0);