LMs // Add documentation to LMCoreNS & LMCoreEX.

Source/Modules/LangModelRelated/SubLMs/lmCoreEX.swift

@@ -23,26 +23,38 @@ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
-/// 與之前的 LMCore 不同，LMCoreEX 不在辭典內記錄實體，而是記錄 range 範圍。
-/// 需要資料的時候，直接拿 range 去 strData 取資料。
-/// 資料記錄原理與上游 C++ 的 ParselessLM 差不多，但用的是 Swift 原生手段。
-/// 主要時間消耗仍在 For 迴圈，但這個算法可以顯著減少記憶體佔用。
-
 import Foundation
 
 extension vChewing {
+  /// 與之前的 LMCore 不同，LMCoreEX 不在辭典內記錄實體，而是記錄 range 範圍。
+  /// 需要資料的時候，直接拿 range 去 strData 取資料。
+  /// 資料記錄原理與上游 C++ 的 ParselessLM 差不多，但用的是 Swift 原生手段。
+  /// 主要時間消耗仍在 For 迴圈，但這個算法可以顯著減少記憶體佔用。
   @frozen public struct LMCoreEX {
+    /// 資料庫陣列。索引內容為注音字串，資料內容則為字串首尾範圍、方便自 strData 取資料。
     var rangeMap: [String: [Range<String.Index>]] = [:]
+    /// 資料庫字串陣列。
     var strData: String = ""
+    /// 聲明原始檔案內第一、二縱列的內容是否彼此顛倒。
     var shouldReverse: Bool = false
     var allowConsolidation: Bool = false
+    /// 當某一筆資料內的權重資料毀損時，要施加的預設權重。
     var defaultScore: Double = 0
+    /// 啟用該選項的話，會強制施加預設權重、而無視原始權重資料。
     var shouldForceDefaultScore: Bool = false
 
+    /// 資料陣列內承載的資料筆數。
     public var count: Int {
       rangeMap.count
     }
 
+    /// 初期化該語言模型。
+    ///
+    /// - parameters:
+    ///   - reverse: 聲明原始檔案內第一、二縱列的內容是否彼此顛倒
+    ///   - consolidate: 請且僅請對使用者語言模組啟用該參數：是否自動整理格式
+    ///   - defaultScore: 當某一筆資料內的權重資料毀損時，要施加的預設權重
+    ///   - forceDefaultScore: 啟用該選項的話，會強制施加預設權重、而無視原始權重資料
     public init(
       reverse: Bool = false, consolidate: Bool = false, defaultScore scoreDefault: Double = 0,
       forceDefaultScore: Bool = false
@@ -54,10 +66,14 @@ extension vChewing {
       shouldForceDefaultScore = forceDefaultScore
     }
 
+    /// 檢測資料庫陣列內是否已經有載入的資料。
     public func isLoaded() -> Bool {
       !rangeMap.isEmpty
     }
 
+    /// 將資料從檔案讀入至資料庫陣列內。
+    /// - parameters:
+    ///   - path: 給定路徑
     @discardableResult public mutating func open(_ path: String) -> Bool {
       if isLoaded() {
         return false
@@ -89,6 +105,7 @@ extension vChewing {
       return true
     }
 
+    /// 將當前語言模組的資料庫陣列自記憶體內卸除。
     public mutating func close() {
       if isLoaded() {
         rangeMap.removeAll()
@@ -97,6 +114,9 @@ extension vChewing {
 
     // MARK: - Advanced features
 
+    /// 將當前資料庫陣列的內容以文本的形式輸出至 macOS 內建的 Console.app。
+    ///
+    /// 該功能僅作偵錯之用途。
     public func dump() {
       var strDump = ""
       for entry in rangeMap {
@@ -110,12 +130,21 @@ extension vChewing {
       IME.prtDebugIntel(strDump)
     }
 
+    /// 【該功能無法使用】根據給定的前述讀音索引鍵與當前讀音索引鍵，來獲取資料庫陣列內的對應資料陣列的字串首尾範圍資料、據此自 strData 取得字串形式的資料、生成雙元圖陣列。
+    ///
+    /// 威注音輸入法尚未引入雙元圖支援，所以該函數並未擴充相關功能，自然不會起作用。
+    /// - parameters:
+    ///   - precedingKey: 前述讀音索引鍵
+    ///   - key: 當前讀音索引鍵
     public func bigramsForKeys(precedingKey: String, key: String) -> [Megrez.Bigram] {
       // 這裡用了點廢話處理，不然函數構建體會被 Swift 格式整理工具給毀掉。
       // 其實只要一句「[Megrez.Bigram]()」就夠了。
       precedingKey == key ? [Megrez.Bigram]() : [Megrez.Bigram]()
     }
 
+    /// 根據給定的讀音索引鍵，來獲取資料庫陣列內的對應資料陣列的字串首尾範圍資料、據此自 strData 取得字串形式的資料、生成單元圖陣列。
+    /// - parameters:
+    ///   - key: 讀音索引鍵
     public func unigramsFor(key: String) -> [Megrez.Unigram] {
       var grams: [Megrez.Unigram] = []
       if let arrRangeRecords: [Range<String.Index>] = rangeMap[key] {
@@ -136,6 +165,9 @@ extension vChewing {
       return grams
     }
 
+    /// 根據給定的讀音索引鍵來確認資料庫陣列內是否存在對應的資料。
+    /// - parameters:
+    ///   - key: 讀音索引鍵
     public func hasUnigramsFor(key: String) -> Bool {
       rangeMap[key] != nil
     }
@@ -145,6 +177,9 @@ extension vChewing {
 // MARK: - StringView Ranges Extension (by Isaac Xen)
 
 extension String {
+  /// 就該字串與給定分隔符、返回每一元素的首尾索引值。
+  /// - parameters:
+  ///   - splitBy: 給定分隔符
   fileprivate func ranges(splitBy separator: Element) -> [Range<String.Index>] {
     var startIndex = startIndex
     return split(separator: separator).reduce(into: []) { ranges, substring in

Source/Modules/LangModelRelated/SubLMs/lmCoreNS.swift

@@ -22,24 +22,40 @@ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
-/// 與之前的 LMCore 不同，LMCoreNS 直接讀取 plist。
-/// 這樣一來可以節省在舊 mac 機種內的資料讀入速度。
-
 import Foundation
 
 extension vChewing {
+  /// 與之前的 LMCore 不同，LMCoreNS 直接讀取 plist。
+  /// 這樣一來可以節省在舊 mac 機種內的資料讀入速度。
+  /// 目前僅針對輸入法原廠語彙資料檔案使用 plist 格式。
   @frozen public struct LMCoreNS {
+    /// 資料庫陣列。索引內容為經過加密的注音字串，資料內容則為 UTF8 資料陣列。
     var rangeMap: [String: [Data]] = [:]
+    /// 【已作廢】資料庫字串陣列。在 LMCoreNS 內沒有作用。
     var strData: String = ""
+    /// 【已作廢】聲明原始檔案內第一、二縱列的內容是否彼此顛倒。
     var shouldReverse: Bool = false
+    /// 請且僅請對使用者語言模組啟用該參數：是否自動整理格式。
     var allowConsolidation: Bool = false
+    /// 當某一筆資料內的權重資料毀損時，要施加的預設權重。
     var defaultScore: Double = 0
+    /// 啟用該選項的話，會強制施加預設權重、而無視原始權重資料。
     var shouldForceDefaultScore: Bool = false
 
+    /// 資料陣列內承載的資料筆數。
     public var count: Int {
       rangeMap.count
     }
 
+    /// 初期化該語言模型。
+    ///
+    /// 某些參數在 LMCoreNS 內已作廢，但仍保留、以方便那些想用該專案源碼做實驗的人群。
+    ///
+    /// - parameters:
+    ///   - reverse: 已作廢：聲明原始檔案內第一、二縱列的內容是否彼此顛倒
+    ///   - consolidate: 請且僅請對使用者語言模組啟用該參數：是否自動整理格式
+    ///   - defaultScore: 當某一筆資料內的權重資料毀損時，要施加的預設權重
+    ///   - forceDefaultScore: 啟用該選項的話，會強制施加預設權重、而無視原始權重資料
     public init(
       reverse: Bool = false, consolidate: Bool = false, defaultScore scoreDefault: Double = 0,
       forceDefaultScore: Bool = false
@@ -51,10 +67,14 @@ extension vChewing {
       shouldForceDefaultScore = forceDefaultScore
     }
 
+    /// 檢測資料庫陣列內是否已經有載入的資料。
     public func isLoaded() -> Bool {
       !rangeMap.isEmpty
     }
 
+    /// 將資料從檔案讀入至資料庫陣列內。
+    /// - parameters:
+    ///   - path: 給定路徑
     @discardableResult public mutating func open(_ path: String) -> Bool {
       if isLoaded() {
         return false
@@ -77,6 +97,7 @@ extension vChewing {
       return true
     }
 
+    /// 將當前語言模組的資料庫陣列自記憶體內卸除。
     public mutating func close() {
       if isLoaded() {
         rangeMap.removeAll()
@@ -85,6 +106,9 @@ extension vChewing {
 
     // MARK: - Advanced features
 
+    /// 將當前資料庫陣列的內容以文本的形式輸出至 macOS 內建的 Console.app。
+    ///
+    /// 該功能僅作偵錯之用途。
     public func dump() {
       var strDump = ""
       for entry in rangeMap {
@@ -104,12 +128,21 @@ extension vChewing {
       IME.prtDebugIntel(strDump)
     }
 
+    /// 【該功能無法使用】根據給定的前述讀音索引鍵與當前讀音索引鍵，來獲取資料庫陣列內的對應資料陣列的 UTF8 資料、就地分析、生成雙元圖陣列。
+    ///
+    /// 威注音輸入法尚未引入雙元圖支援，所以該函數並未擴充相關功能，自然不會起作用。
+    /// - parameters:
+    ///   - precedingKey: 前述讀音索引鍵
+    ///   - key: 當前讀音索引鍵
     public func bigramsForKeys(precedingKey: String, key: String) -> [Megrez.Bigram] {
       // 這裡用了點廢話處理，不然函數構建體會被 Swift 格式整理工具給毀掉。
       // 其實只要一句「[Megrez.Bigram]()」就夠了。
       precedingKey == key ? [Megrez.Bigram]() : [Megrez.Bigram]()
     }
 
+    /// 根據給定的讀音索引鍵，來獲取資料庫陣列內的對應資料陣列的 UTF8 資料、就地分析、生成單元圖陣列。
+    /// - parameters:
+    ///   - key: 讀音索引鍵
     public func unigramsFor(key: String) -> [Megrez.Unigram] {
       var grams: [Megrez.Unigram] = []
       if let arrRangeRecords: [Data] = rangeMap[cnvPhonabetToASCII(key)] {
@@ -131,10 +164,20 @@ extension vChewing {
       return grams
     }
 
+    /// 根據給定的讀音索引鍵來確認資料庫陣列內是否存在對應的資料。
+    /// - parameters:
+    ///   - key: 讀音索引鍵
     public func hasUnigramsFor(key: String) -> Bool {
       rangeMap[cnvPhonabetToASCII(key)] != nil
     }
 
+    /// 內部函數，用以將注音讀音索引鍵進行加密。
+    ///
+    /// 使用這種加密字串作為索引鍵，可以增加對 plist 資料庫的存取速度。
+    ///
+    /// 如果傳入的字串當中包含 ASCII 下畫線符號的話，則表明該字串並非注音讀音字串，會被忽略處理。
+    /// - parameters:
+    ///   - incoming: 傳入的未加密注音讀音字串
     func cnvPhonabetToASCII(_ incoming: String) -> String {
       let dicPhonabet2ASCII = [
         "ㄅ": "b", "ㄆ": "p", "ㄇ": "m", "ㄈ": "f", "ㄉ": "d", "ㄊ": "t", "ㄋ": "n", "ㄌ": "l", "ㄍ": "g", "ㄎ": "k", "ㄏ": "h",
@@ -151,6 +194,11 @@ extension vChewing {
       return strOutput
     }
 
+    /// 內部函數，用以將被加密的注音讀音索引鍵進行解密。
+    ///
+    /// 如果傳入的字串當中包含 ASCII 下畫線符號的話，則表明該字串並非注音讀音字串，會被忽略處理。
+    /// - parameters:
+    ///   - incoming: 傳入的已加密注音讀音字串
     func restorePhonabetFromASCII(_ incoming: String) -> String {
       let dicPhonabet4ASCII = [
         "b": "ㄅ", "p": "ㄆ", "m": "ㄇ", "f": "ㄈ", "d": "ㄉ", "t": "ㄊ", "n": "ㄋ", "l": "ㄌ", "g": "ㄍ", "k": "ㄎ", "h": "ㄏ",