From 65ae342bcaabf79ab3d010e2b260e40de57f5f8d Mon Sep 17 00:00:00 2001
From: Jack251970 <1160210343@qq.com>
Date: Mon, 24 Feb 2025 15:37:13 +0800
Subject: [PATCH] Add documents for Flow.Launcher.Plugin

---
 Flow.Launcher.Plugin/ActionContext.cs         |  3 ++
 .../Interfaces/IResultUpdated.cs              | 27 +++++++++++-
 .../Interfaces/ISettingProvider.cs            |  7 ++++
 Flow.Launcher.Plugin/PluginInitContext.cs     |  8 ++++
 Flow.Launcher.Plugin/PluginPair.cs            | 28 +++++++++++--
 Flow.Launcher.Plugin/Query.cs                 |  7 ++--
 Flow.Launcher.Plugin/Result.cs                |  2 -
 .../SharedCommands/SearchWeb.cs               |  5 ++-
 .../SharedCommands/ShellCommand.cs            | 23 ++++++++++
 .../SharedModels/MatchResult.cs               | 42 +++++++++++++++++++
 10 files changed, 141 insertions(+), 11 deletions(-)

diff --git a/Flow.Launcher.Plugin/ActionContext.cs b/Flow.Launcher.Plugin/ActionContext.cs
index e31c8e31d..9e05bbd06 100644
--- a/Flow.Launcher.Plugin/ActionContext.cs
+++ b/Flow.Launcher.Plugin/ActionContext.cs
@@ -51,6 +51,9 @@ namespace Flow.Launcher.Plugin
                    (WinPressed ? ModifierKeys.Windows : ModifierKeys.None);
         }
 
+        /// <summary>
+        /// Default <see cref="SpecialKeyState"/> object with all keys not pressed.
+        /// </summary>
         public static readonly SpecialKeyState Default = new () {
             CtrlPressed = false,
             ShiftPressed = false,
diff --git a/Flow.Launcher.Plugin/Interfaces/IResultUpdated.cs b/Flow.Launcher.Plugin/Interfaces/IResultUpdated.cs
index fd21460ac..aa4e4a56d 100644
--- a/Flow.Launcher.Plugin/Interfaces/IResultUpdated.cs
+++ b/Flow.Launcher.Plugin/Interfaces/IResultUpdated.cs
@@ -4,17 +4,42 @@ using System.Threading;
 
 namespace Flow.Launcher.Plugin
 {
+    /// <summary>
+    /// Interface for plugins that want to manually update their results
+    /// </summary>
     public interface IResultUpdated : IFeatures
     {
+        /// <summary>
+        /// Event that is triggered when the results are updated
+        /// </summary>
         event ResultUpdatedEventHandler ResultsUpdated;
     }
 
+    /// <summary>
+    /// Delegate for the ResultsUpdated event
+    /// </summary>
+    /// <param name="sender"></param>
+    /// <param name="e"></param>
     public delegate void ResultUpdatedEventHandler(IResultUpdated sender, ResultUpdatedEventArgs e);
 
+    /// <summary>
+    /// Event arguments for the ResultsUpdated event
+    /// </summary>
     public class ResultUpdatedEventArgs : EventArgs
     {
+        /// <summary>
+        /// List of results that should be displayed
+        /// </summary>
         public List<Result> Results;
+
+        /// <summary>
+        /// Query that triggered the update
+        /// </summary>
         public Query Query;
+
+        /// <summary>
+        /// Token that can be used to cancel the update
+        /// </summary>
         public CancellationToken Token { get; init; }
     }
-}
\ No newline at end of file
+}
diff --git a/Flow.Launcher.Plugin/Interfaces/ISettingProvider.cs b/Flow.Launcher.Plugin/Interfaces/ISettingProvider.cs
index d5ffba20b..f034243c3 100644
--- a/Flow.Launcher.Plugin/Interfaces/ISettingProvider.cs
+++ b/Flow.Launcher.Plugin/Interfaces/ISettingProvider.cs
@@ -2,8 +2,15 @@
 
 namespace Flow.Launcher.Plugin
 {
+    /// <summary>
+    /// This interface is used to create settings panel for .Net plugins
+    /// </summary>
     public interface ISettingProvider
     {
+        /// <summary>
+        /// Create settings panel control for .Net plugins
+        /// </summary>
+        /// <returns></returns>
         Control CreateSettingPanel();
     }
 }
diff --git a/Flow.Launcher.Plugin/PluginInitContext.cs b/Flow.Launcher.Plugin/PluginInitContext.cs
index f040752bd..a42e3930c 100644
--- a/Flow.Launcher.Plugin/PluginInitContext.cs
+++ b/Flow.Launcher.Plugin/PluginInitContext.cs
@@ -5,10 +5,18 @@
     /// </summary>
     public class PluginInitContext
     {
+        /// <summary>
+        /// Default constructor.
+        /// </summary>
         public PluginInitContext()
         {
         }
 
+        /// <summary>
+        /// Constructor.
+        /// </summary>
+        /// <param name="currentPluginMetadata"></param>
+        /// <param name="api"></param>
         public PluginInitContext(PluginMetadata currentPluginMetadata, IPublicAPI api)
         {
             CurrentPluginMetadata = currentPluginMetadata;
diff --git a/Flow.Launcher.Plugin/PluginPair.cs b/Flow.Launcher.Plugin/PluginPair.cs
index 7bf634691..037af7427 100644
--- a/Flow.Launcher.Plugin/PluginPair.cs
+++ b/Flow.Launcher.Plugin/PluginPair.cs
@@ -1,21 +1,37 @@
 namespace Flow.Launcher.Plugin
 {
+    /// <summary>
+    /// Plugin instance and plugin metadata
+    /// </summary>
     public class PluginPair
     {
+        /// <summary>
+        /// Plugin instance
+        /// </summary>
         public IAsyncPlugin Plugin { get; internal set; }
+
+        /// <summary>
+        /// Plugin metadata
+        /// </summary>
         public PluginMetadata Metadata { get; internal set; }
 
-        
-
+        /// <summary>
+        /// Convert to string
+        /// </summary>
+        /// <returns></returns>
         public override string ToString()
         {
             return Metadata.Name;
         }
 
+        /// <summary>
+        /// Compare by plugin metadata ID
+        /// </summary>
+        /// <param name="obj"></param>
+        /// <returns></returns>
         public override bool Equals(object obj)
         {
-            PluginPair r = obj as PluginPair;
-            if (r != null)
+            if (obj is PluginPair r)
             {
                 return string.Equals(r.Metadata.ID, Metadata.ID);
             }
@@ -25,6 +41,10 @@
             }
         }
 
+        /// <summary>
+        /// Get hash coode
+        /// </summary>
+        /// <returns></returns>
         public override int GetHashCode()
         {
             var hashcode = Metadata.ID?.GetHashCode() ?? 0;
diff --git a/Flow.Launcher.Plugin/Query.cs b/Flow.Launcher.Plugin/Query.cs
index e182491c2..a9694e263 100644
--- a/Flow.Launcher.Plugin/Query.cs
+++ b/Flow.Launcher.Plugin/Query.cs
@@ -2,10 +2,11 @@
 
 namespace Flow.Launcher.Plugin
 {
+    /// <summary>
+    /// Represents a query that is sent to a plugin.
+    /// </summary>
     public class Query
     {
-        public Query() { }
-
         /// <summary>
         /// Raw query, this includes action keyword if it has
         /// We didn't recommend use this property directly. You should always use Search property.
@@ -55,13 +56,13 @@ namespace Flow.Launcher.Plugin
         /// </summary>
         public string ActionKeyword { get; init; }
 
-        [JsonIgnore]
         /// <summary>
         /// Splits <see cref="SearchTerms"/> by spaces and returns the first item.
         /// </summary>
         /// <remarks>
         /// returns an empty string when <see cref="SearchTerms"/> does not have enough items.
         /// </remarks>
+        [JsonIgnore]
         public string FirstSearch => SplitSearch(0);
         
         [JsonIgnore]
diff --git a/Flow.Launcher.Plugin/Result.cs b/Flow.Launcher.Plugin/Result.cs
index 9b16cc1cb..910485438 100644
--- a/Flow.Launcher.Plugin/Result.cs
+++ b/Flow.Launcher.Plugin/Result.cs
@@ -1,5 +1,4 @@
 using System;
-using System.Runtime;
 using System.Collections.Generic;
 using System.IO;
 using System.Threading.Tasks;
@@ -13,7 +12,6 @@ namespace Flow.Launcher.Plugin
     /// </summary>
     public class Result
     {
-
         private string _pluginDirectory;
 
         private string _icoPath;
diff --git a/Flow.Launcher.Plugin/SharedCommands/SearchWeb.cs b/Flow.Launcher.Plugin/SharedCommands/SearchWeb.cs
index a7744ffac..752c85933 100644
--- a/Flow.Launcher.Plugin/SharedCommands/SearchWeb.cs
+++ b/Flow.Launcher.Plugin/SharedCommands/SearchWeb.cs
@@ -6,6 +6,9 @@ using System.Linq;
 
 namespace Flow.Launcher.Plugin.SharedCommands
 {
+    /// <summary>
+    /// Contains methods to open a search in a new browser window or tab.
+    /// </summary>
     public static class SearchWeb
     {
         private static string GetDefaultBrowserPath()
@@ -106,4 +109,4 @@ namespace Flow.Launcher.Plugin.SharedCommands
             }
         }
     }
-}
\ No newline at end of file
+}
diff --git a/Flow.Launcher.Plugin/SharedCommands/ShellCommand.cs b/Flow.Launcher.Plugin/SharedCommands/ShellCommand.cs
index a0440e30d..288222d4f 100644
--- a/Flow.Launcher.Plugin/SharedCommands/ShellCommand.cs
+++ b/Flow.Launcher.Plugin/SharedCommands/ShellCommand.cs
@@ -8,12 +8,26 @@ using Windows.Win32.Foundation;
 
 namespace Flow.Launcher.Plugin.SharedCommands
 {
+    /// <summary>
+    /// Contains methods for running shell commands
+    /// </summary>
     public static class ShellCommand
     {
+        /// <summary>
+        /// Delegate for EnumThreadWindows
+        /// </summary>
+        /// <param name="hwnd"></param>
+        /// <param name="lParam"></param>
+        /// <returns></returns>
         public delegate bool EnumThreadDelegate(IntPtr hwnd, IntPtr lParam);
 
         private static bool containsSecurityWindow;
 
+        /// <summary>
+        /// Runs a windows command using the provided ProcessStartInfo
+        /// </summary>
+        /// <param name="processStartInfo"></param>
+        /// <returns></returns>
         public static Process RunAsDifferentUser(ProcessStartInfo processStartInfo)
         {
             processStartInfo.Verb = "RunAsUser";
@@ -65,6 +79,15 @@ namespace Flow.Launcher.Plugin.SharedCommands
             return buffer[..length].ToString();
         }
 
+        /// <summary>
+        /// Runs a windows command using the provided ProcessStartInfo
+        /// </summary>
+        /// <param name="fileName"></param>
+        /// <param name="workingDirectory"></param>
+        /// <param name="arguments"></param>
+        /// <param name="verb"></param>
+        /// <param name="createNoWindow"></param>
+        /// <returns></returns>
         public static ProcessStartInfo SetProcessStartInfo(this string fileName, string workingDirectory = "",
             string arguments = "", string verb = "", bool createNoWindow = false)
         {
diff --git a/Flow.Launcher.Plugin/SharedModels/MatchResult.cs b/Flow.Launcher.Plugin/SharedModels/MatchResult.cs
index 5144eb61d..36677d4bb 100644
--- a/Flow.Launcher.Plugin/SharedModels/MatchResult.cs
+++ b/Flow.Launcher.Plugin/SharedModels/MatchResult.cs
@@ -2,14 +2,29 @@
 
 namespace Flow.Launcher.Plugin.SharedModels
 {
+    /// <summary>
+    /// Represents the result of a match operation.
+    /// </summary>
     public class MatchResult
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MatchResult"/> class.
+        /// </summary>
+        /// <param name="success"></param>
+        /// <param name="searchPrecision"></param>
         public MatchResult(bool success, SearchPrecisionScore searchPrecision)
         {
             Success = success;
             SearchPrecision = searchPrecision;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="MatchResult"/> class.
+        /// </summary>
+        /// <param name="success"></param>
+        /// <param name="searchPrecision"></param>
+        /// <param name="matchData"></param>
+        /// <param name="rawScore"></param>
         public MatchResult(bool success, SearchPrecisionScore searchPrecision, List<int> matchData, int rawScore)
         {
             Success = success;
@@ -18,6 +33,9 @@ namespace Flow.Launcher.Plugin.SharedModels
             RawScore = rawScore;
         }
 
+        /// <summary>
+        /// Whether the match operation was successful.
+        /// </summary>
         public bool Success { get; set; }
 
         /// <summary>
@@ -30,6 +48,9 @@ namespace Flow.Launcher.Plugin.SharedModels
         /// </summary>
         private int _rawScore;
 
+        /// <summary>
+        /// The raw calculated search score without any search precision filtering applied.
+        /// </summary>
         public int RawScore
         {
             get { return _rawScore; }
@@ -45,8 +66,15 @@ namespace Flow.Launcher.Plugin.SharedModels
         /// </summary>
         public List<int> MatchData { get; set; }
 
+        /// <summary>
+        /// The search precision score used to filter the search results.
+        /// </summary>
         public SearchPrecisionScore SearchPrecision { get; set; }
 
+        /// <summary>
+        /// Determines if the search precision score is met.
+        /// </summary>
+        /// <returns></returns>
         public bool IsSearchPrecisionScoreMet()
         {
             return IsSearchPrecisionScoreMet(_rawScore);
@@ -63,10 +91,24 @@ namespace Flow.Launcher.Plugin.SharedModels
         }
     }
 
+    /// <summary>
+    /// Represents the search precision score used to filter search results.
+    /// </summary>
     public enum SearchPrecisionScore
     {
+        /// <summary>
+        /// The highest search precision score.
+        /// </summary>
         Regular = 50,
+
+        /// <summary>
+        /// The medium search precision score.
+        /// </summary>
         Low = 20,
+
+        /// <summary>
+        /// The lowest search precision score.
+        /// </summary>
         None = 0
     }
 }