From a50c578a138fc05e3738eef09e6c9fb50b73d116 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Thu, 19 Jun 2025 11:06:31 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`double-?= =?UTF-8?q?pin`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @VictoriousRaptor. * https://github.com/Flow-Launcher/Flow.Launcher/pull/2427#issuecomment-2980562859 The following files were modified: * `Flow.Launcher.Infrastructure/IAlphabet.cs` * `Flow.Launcher.Infrastructure/PinyinAlphabet.cs` * `Flow.Launcher.Infrastructure/StringMatcher.cs` * `Flow.Launcher.Infrastructure/TranslationMapping.cs` --- Flow.Launcher.Infrastructure/IAlphabet.cs | 14 ++++-- .../PinyinAlphabet.cs | 46 ++++++++++++++++++- Flow.Launcher.Infrastructure/StringMatcher.cs | 21 ++++++++- .../TranslationMapping.cs | 18 +++++++- 4 files changed, 92 insertions(+), 7 deletions(-) diff --git a/Flow.Launcher.Infrastructure/IAlphabet.cs b/Flow.Launcher.Infrastructure/IAlphabet.cs index e79ec0c6d..65ee07b24 100644 --- a/Flow.Launcher.Infrastructure/IAlphabet.cs +++ b/Flow.Launcher.Infrastructure/IAlphabet.cs @@ -1,4 +1,4 @@ -namespace Flow.Launcher.Infrastructure +namespace Flow.Launcher.Infrastructure { /// /// Translate a language to English letters using a given rule. @@ -9,14 +9,22 @@ /// Translate a string to English letters, using a given rule. /// /// String to translate. - /// + /// +/// Translates the input string into English letters according to the implementing alphabet's rules. +/// +/// The string to be translated. +/// A tuple containing the translated string and a representing the mapping details. public (string translation, TranslationMapping map) Translate(string stringToTranslate); /// /// Determine if a string can be translated to English letter with this Alphabet. /// /// String to translate. - /// + /// +/// Determines whether the specified string is eligible for translation to English letters using this alphabet's rules. +/// +/// The input string to evaluate for translation eligibility. +/// True if the string should be translated; otherwise, false. public bool ShouldTranslate(string stringToTranslate); } } diff --git a/Flow.Launcher.Infrastructure/PinyinAlphabet.cs b/Flow.Launcher.Infrastructure/PinyinAlphabet.cs index 37b7bb8c3..c82d92629 100644 --- a/Flow.Launcher.Infrastructure/PinyinAlphabet.cs +++ b/Flow.Launcher.Infrastructure/PinyinAlphabet.cs @@ -1,4 +1,4 @@ -using System; +using System; using System.Collections.Concurrent; using System.Collections.Generic; using System.Collections.ObjectModel; @@ -21,6 +21,9 @@ namespace Flow.Launcher.Infrastructure private ReadOnlyDictionary currentDoublePinyinTable; + /// + /// Initializes a new instance of the class, loading the double Pinyin table based on current settings and subscribing to setting changes to reload the table and clear the cache as needed. + /// public PinyinAlphabet() { _settings = Ioc.Default.GetRequiredService(); @@ -36,12 +39,22 @@ namespace Flow.Launcher.Infrastructure }; } + /// + /// Reloads the double Pinyin mapping table and clears the translation cache. + /// public void Reload() { LoadDoublePinyinTable(); _pinyinCache.Clear(); } + /// + /// Loads the double Pinyin mapping table for the current schema from a JSON stream. + /// + /// A stream containing the double Pinyin tables in JSON format. + /// + /// Thrown if the current double Pinyin schema is invalid or the table is missing from the JSON. + /// private void CreateDoublePinyinTableFromStream(Stream jsonStream) { Dictionary> table = JsonSerializer.Deserialize>>(jsonStream); @@ -52,6 +65,9 @@ namespace Flow.Launcher.Infrastructure currentDoublePinyinTable = new ReadOnlyDictionary(value); } + /// + /// Loads the double Pinyin mapping table from a JSON file if enabled in settings; sets an empty table if loading fails or double Pinyin is disabled. + /// private void LoadDoublePinyinTable() { if (_settings.UseDoublePinyin) @@ -74,6 +90,13 @@ namespace Flow.Launcher.Infrastructure } } + /// + /// Determines whether the specified string should be translated based on current settings and its content. + /// + /// The string to evaluate for translation eligibility. + /// + /// True if the string contains no Chinese characters and, when double Pinyin is enabled, has an even length; otherwise, false. + /// public bool ShouldTranslate(string stringToTranslate) { return _settings.UseDoublePinyin ? @@ -81,6 +104,14 @@ namespace Flow.Launcher.Infrastructure !WordsHelper.HasChinese(stringToTranslate); } + /// + /// Translates the input string to Pinyin, returning the translated string and its mapping. + /// + /// The string to translate. + /// + /// A tuple containing the translated Pinyin string and a object. + /// If Pinyin translation is disabled or the input contains no Chinese characters, returns the original string and null mapping. + /// public (string translation, TranslationMapping map) Translate(string content) { if (!_settings.ShouldUsePinyin || !WordsHelper.HasChinese(content)) @@ -91,6 +122,13 @@ namespace Flow.Launcher.Infrastructure : BuildCacheFromContent(content); } + /// + /// Generates the Pinyin or double Pinyin translation and mapping for the given content. + /// + /// The input string to translate. + /// + /// A tuple containing the translated string and a correlating original and translated indices. + /// private (string translation, TranslationMapping map) BuildCacheFromContent(string content) { var resultList = WordsHelper.GetPinyinList(content); @@ -138,6 +176,12 @@ namespace Flow.Launcher.Infrastructure #region Double Pinyin + /// + /// Converts a full Pinyin syllable to its double Pinyin equivalent using the current mapping table. + /// Returns the original Pinyin if no mapping exists. + /// + /// The full Pinyin syllable to convert. + /// The double Pinyin equivalent if found; otherwise, the original full Pinyin. private string ToDoublePin(string fullPinyin) { if (currentDoublePinyinTable.TryGetValue(fullPinyin, out var doublePinyinValue)) diff --git a/Flow.Launcher.Infrastructure/StringMatcher.cs b/Flow.Launcher.Infrastructure/StringMatcher.cs index 2882cb8f0..4401e3b87 100644 --- a/Flow.Launcher.Infrastructure/StringMatcher.cs +++ b/Flow.Launcher.Infrastructure/StringMatcher.cs @@ -1,4 +1,4 @@ -using CommunityToolkit.Mvvm.DependencyInjection; +using CommunityToolkit.Mvvm.DependencyInjection; using Flow.Launcher.Plugin.SharedModels; using System; using System.Collections.Generic; @@ -60,7 +60,13 @@ namespace Flow.Launcher.Infrastructure /// 5. Once the previous character is verified, move on to the next character in the query substring. /// 6. Move onto the next substring's characters until all substrings are checked. /// 7. Consider success and move onto scoring if every char or substring without whitespaces matched + /// + /// Performs fuzzy and acronym-based matching between a query and a target string, returning match details and a relevance score. /// + /// The search query to match against the target string. + /// The string to be compared with the query. + /// Options that control matching behavior, such as case sensitivity. + /// A indicating whether a match was found, the indices of matched characters, and the computed match score. public MatchResult FuzzyMatch(string query, string stringToCompare, MatchOption opt) { if (string.IsNullOrEmpty(stringToCompare) || string.IsNullOrEmpty(query)) @@ -228,6 +234,12 @@ namespace Flow.Launcher.Infrastructure return new MatchResult(false, UserSettingSearchPrecision); } + /// + /// Determines whether the character at the specified index in the string is considered part of an acronym, either by being an acronym character or a digit. + /// + /// The string to evaluate. + /// The index of the character to check. + /// True if the character is an acronym character or a digit; otherwise, false. private static bool IsAcronym(string stringToCompare, int compareStringIndex) { if (IsAcronymChar(stringToCompare, compareStringIndex) || IsAcronymNumber(stringToCompare, compareStringIndex)) @@ -236,7 +248,12 @@ namespace Flow.Launcher.Infrastructure return false; } - // When counting acronyms, treat a set of numbers as one acronym ie. Visual 2019 as 2 acronyms instead of 5 + /// + /// Determines whether the character at the specified index should be counted as a distinct acronym character, treating consecutive numbers as a single acronym. + /// + /// The string being analyzed for acronym characters. + /// The index of the character to evaluate. + /// True if the character is an acronym character or the start of a numeric sequence; otherwise, false. private static bool IsAcronymCount(string stringToCompare, int compareStringIndex) { if (IsAcronymChar(stringToCompare, compareStringIndex)) diff --git a/Flow.Launcher.Infrastructure/TranslationMapping.cs b/Flow.Launcher.Infrastructure/TranslationMapping.cs index b33a094db..dbe15aaa1 100644 --- a/Flow.Launcher.Infrastructure/TranslationMapping.cs +++ b/Flow.Launcher.Infrastructure/TranslationMapping.cs @@ -1,4 +1,4 @@ -using System; +using System; using System.Collections.Generic; using System.Linq; @@ -13,6 +13,13 @@ namespace Flow.Launcher.Infrastructure private int translatedLength = 0; + /// + /// Adds a mapping between an original index and a translated index range. + /// + /// The index in the original sequence. + /// The starting index of the corresponding range in the translated sequence. + /// The length of the translated index range. + /// Thrown if the mapping has already been finalized. public void AddNewIndex(int originalIndex, int translatedIndex, int length) { if (constructed) @@ -24,6 +31,11 @@ namespace Flow.Launcher.Infrastructure translatedLength += length - 1; } + /// + /// Maps a translated index back to its corresponding original index based on stored translation ranges. + /// + /// The index in the translated sequence to map. + /// The corresponding index in the original sequence. If the translated index falls outside known ranges, returns an adjusted index based on accumulated translation lengths. public int MapToOriginalIndex(int translatedIndex) { if (translatedIndex > translatedIndexes.Last()) @@ -86,6 +98,10 @@ namespace Flow.Launcher.Infrastructure } } + /// + /// Finalizes the mapping, preventing any further modifications. + /// + /// Thrown if the mapping has already been finalized. public void endConstruct() { if (constructed)