From 763b51858fc094eb158b98ef023f9ccb24d8d44a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=98=E9=9F=AC=20=E5=BC=A0?= <hongtao_zhang@outlook.com>
Date: Thu, 14 Jan 2021 12:24:41 +0800
Subject: [PATCH] Add comment in IPublic, IAsyncPlugin, IReloadable,
 IAsyncReloadable

---
 Flow.Launcher.Plugin/IAsyncPlugin.cs          | 15 +++++++++++++
 Flow.Launcher.Plugin/IPlugin.cs               | 22 ++++++++++++++++++-
 .../Interfaces/IAsyncReloadable.cs            | 11 ++++++++++
 .../Interfaces/IReloadable.cs                 |  6 ++++-
 4 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/Flow.Launcher.Plugin/IAsyncPlugin.cs b/Flow.Launcher.Plugin/IAsyncPlugin.cs
index 36f098e7d..3e1a086bc 100644
--- a/Flow.Launcher.Plugin/IAsyncPlugin.cs
+++ b/Flow.Launcher.Plugin/IAsyncPlugin.cs
@@ -4,9 +4,24 @@ using System.Threading.Tasks;
 
 namespace Flow.Launcher.Plugin
 {
+    /// <summary>
+    /// Asynchronous Plugin Model for Flow Launcher
+    /// </summary>
     public interface IAsyncPlugin
     {
+        /// <summary>
+        /// Asynchronous Querying
+        /// </summary>
+        /// <param name="query">Query to search</param>
+        /// <param name="token">Cancel when querying job is obsolete</param>
+        /// <returns></returns>
         Task<List<Result>> QueryAsync(Query query, CancellationToken token);
+
+        /// <summary>
+        /// Initialize plugin asynchrously (will still wait finish to continue)
+        /// </summary>
+        /// <param name="context"></param>
+        /// <returns></returns>
         Task InitAsync(PluginInitContext context);
     }
 }
\ No newline at end of file
diff --git a/Flow.Launcher.Plugin/IPlugin.cs b/Flow.Launcher.Plugin/IPlugin.cs
index 4cc6d8d40..41c61a608 100644
--- a/Flow.Launcher.Plugin/IPlugin.cs
+++ b/Flow.Launcher.Plugin/IPlugin.cs
@@ -2,10 +2,30 @@
 
 namespace Flow.Launcher.Plugin
 {
+    /// <summary>
+    /// Synchronous Plugin Model for Flow Launcher
+    /// <para>
+    /// If you assume that Querying or Init method require IO transmission
+    /// or CPU Intense Job (performing better with cancellation), please try IAsyncPlugin interface
+    /// </para>
+    /// </summary>
     public interface IPlugin
     {
+        /// <summary>
+        /// Querying when user's search changes
+        /// <para>
+        /// This method will be called within a Task.Run,
+        /// so please avoid synchrously wait for long.
+        /// </para>
+        /// </summary>
+        /// <param name="query">Query to search</param>
+        /// <returns></returns>
         List<Result> Query(Query query);
-        
+
+        /// <summary>
+        /// Initialize plugin
+        /// </summary>
+        /// <param name="context"></param>
         void Init(PluginInitContext context);
     }
 }
\ No newline at end of file
diff --git a/Flow.Launcher.Plugin/Interfaces/IAsyncReloadable.cs b/Flow.Launcher.Plugin/Interfaces/IAsyncReloadable.cs
index 9c922f667..434d83646 100644
--- a/Flow.Launcher.Plugin/Interfaces/IAsyncReloadable.cs
+++ b/Flow.Launcher.Plugin/Interfaces/IAsyncReloadable.cs
@@ -2,6 +2,17 @@
 
 namespace Flow.Launcher.Plugin
 {
+    /// <summary>
+    /// This interface is to indicate and allow plugins to asyncronously reload their
+    /// in memory data cache or other mediums when user makes a new change
+    /// that is not immediately captured. For example, for BrowserBookmark and Program
+    /// plugin does not automatically detect when a user added a new bookmark or program,
+    /// so this interface's function is exposed to allow user manually do the reloading after 
+    /// those new additions.
+    /// 
+    /// The command that allows user to manual reload is exposed via Plugin.Sys, and
+    /// it will call the plugins that have implemented this interface.
+    /// </summary>
     public interface IAsyncReloadable
     {
         Task ReloadDataAsync();
diff --git a/Flow.Launcher.Plugin/Interfaces/IReloadable.cs b/Flow.Launcher.Plugin/Interfaces/IReloadable.cs
index 29b3c15c9..d9160b0ea 100644
--- a/Flow.Launcher.Plugin/Interfaces/IReloadable.cs
+++ b/Flow.Launcher.Plugin/Interfaces/IReloadable.cs
@@ -1,7 +1,7 @@
 namespace Flow.Launcher.Plugin
 {
     /// <summary>
-    /// This interface is to indicate and allow plugins to reload their
+    /// This interface is to indicate and allow plugins to synchronously reload their
     /// in memory data cache or other mediums when user makes a new change
     /// that is not immediately captured. For example, for BrowserBookmark and Program
     /// plugin does not automatically detect when a user added a new bookmark or program,
@@ -10,6 +10,10 @@
     /// 
     /// The command that allows user to manual reload is exposed via Plugin.Sys, and
     /// it will call the plugins that have implemented this interface.
+    /// 
+    /// <para>
+    /// If requiring reloading data asynchrouly, please try IAsyncReloadable
+    /// </para>
     /// </summary>
     public interface IReloadable
     {