From 9b5fbeef9b5986c306b21da45900757bfeacb3c1 Mon Sep 17 00:00:00 2001
From: Ioannis G <jtgftw@gmail.com>
Date: Sun, 18 Jun 2023 21:59:03 +0300
Subject: [PATCH] update documentation in Result

---
 Flow.Launcher.Plugin/Result.cs | 67 +++++++++++++++++++++++-----------
 1 file changed, 46 insertions(+), 21 deletions(-)

diff --git a/Flow.Launcher.Plugin/Result.cs b/Flow.Launcher.Plugin/Result.cs
index 1c4467762..6810a6d47 100644
--- a/Flow.Launcher.Plugin/Result.cs
+++ b/Flow.Launcher.Plugin/Result.cs
@@ -8,7 +8,7 @@ using System.Windows.Media;
 namespace Flow.Launcher.Plugin
 {
     /// <summary>
-    /// Describes the result of a plugin
+    /// Describes a result of a <see cref="Query"/> executed by a plugin
     /// </summary>
     public class Result
     {
@@ -17,6 +17,8 @@ namespace Flow.Launcher.Plugin
 
         private string _icoPath;
 
+        private string _copyText = string.Empty;
+
         /// <summary>
         /// The title of the result. This is always required.
         /// </summary>
@@ -28,13 +30,13 @@ namespace Flow.Launcher.Plugin
         public string SubTitle { get; set; } = string.Empty;
 
         /// <summary>
-        /// This holds the action keyword that triggered the result. 
+        /// This holds the action keyword that triggered the result.
         /// If result is triggered by global keyword: *, this should be empty.
         /// </summary>
         public string ActionKeywordAssigned { get; set; }
 
         /// <summary>
-        /// This holds the text which can be provided by plugin to be copied to the 
+        /// This holds the text which can be provided by plugin to be copied to the
         /// user's clipboard when Ctrl + C is pressed on a result. If the text is a file/directory path
         /// flow will copy the actual file/folder instead of just the path text.
         /// </summary>
@@ -46,16 +48,17 @@ namespace Flow.Launcher.Plugin
 
         /// <summary>
         /// This holds the text which can be provided by plugin to help Flow autocomplete text
-        /// for user on the plugin result. If autocomplete action for example is tab, pressing tab will have 
+        /// for user on the plugin result. If autocomplete action for example is tab, pressing tab will have
         /// the default constructed autocomplete text (result's Title), or the text provided here if not empty.
         /// </summary>
+        /// <remarks>When a value is not set, the <see cref="Title"/> will be used.</remarks>
         public string AutoCompleteText { get; set; }
 
         /// <summary>
-        /// Image Displayed on the result
-        /// <value>Relative Path to the Image File</value>
-        /// <remarks>GlyphInfo is prioritized if not null</remarks>
+        /// The image to be displayed for the result.
         /// </summary>
+        /// <value>Can be a local file path or a URL.</value>
+        /// <remarks>GlyphInfo is prioritized if not null</remarks>
         public string IcoPath
         {
             get { return _icoPath; }
@@ -76,22 +79,22 @@ namespace Flow.Launcher.Plugin
                 }
             }
         }
+
         /// <summary>
         /// Determines if Icon has a border radius
         /// </summary>
         public bool RoundedIcon { get; set; } = false;
 
         /// <summary>
-        /// Delegate function, see <see cref="Icon"/>
+        /// Delegate function that produces an <see cref="ImageSource"/>
         /// </summary>
         /// <returns></returns>
         public delegate ImageSource IconDelegate();
 
         /// <summary>
-        /// Delegate to Get Image Source
+        /// Delegate to load an icon for this result.
         /// </summary>
         public IconDelegate Icon;
-        private string _copyText = string.Empty;
 
         /// <summary>
         /// Information for Glyph Icon (Prioritized than IcoPath/Icon if user enable Glyph Icons)
@@ -100,25 +103,29 @@ namespace Flow.Launcher.Plugin
 
 
         /// <summary>
-        /// Delegate. An action to take in the form of a function call when the result has been selected
-        /// <returns>
-        /// true to hide flowlauncher after select result
-        /// </returns>
+        /// An action to take in the form of a function call when the result has been selected.
         /// </summary>
+        /// <remarks>
+        /// The function is invoked with an <see cref="ActionContext"/> as the only parameter.
+        /// Its result determines what happens to Flow Launcher's query form:
+        /// when true, the form will be hidden; when false, it will stay in focus.
+        /// </remarks>
         public Func<ActionContext, bool> Action { get; set; }
 
         /// <summary>
-        /// Delegate. An Async action to take in the form of a function call when the result has been selected
-        /// <returns>
-        /// true to hide flowlauncher after select result
-        /// </returns>
+        /// An async action to take in the form of a function call when the result has been selected.
         /// </summary>
+        /// <remarks>
+        /// The function is invoked with an <see cref="ActionContext"/> as the only parameter and awaited.
+        /// Its result determines what happens to Flow Launcher's query form:
+        /// when true, the form will be hidden; when false, it will stay in focus.
+        /// </remarks>
         public Func<ActionContext, ValueTask<bool>> AsyncAction { get; set; }
 
         /// <summary>
         /// Priority of the current result
-        /// <value>default: 0</value>
         /// </summary>
+        /// <value>default: 0</value>
         public int Score { get; set; }
 
         /// <summary>
@@ -183,10 +190,10 @@ namespace Flow.Launcher.Plugin
 
         /// <summary>
         /// Additional data associated with this result
+        /// </summary>
         /// <example>
         /// As external information for ContextMenu
         /// </example>
-        /// </summary>
         public object ContextData { get; set; }
 
         /// <summary>
@@ -230,10 +237,13 @@ namespace Flow.Launcher.Plugin
         /// <default>#26a0da (blue)</default>
         public string ProgressBarColor { get; set; } = "#26a0da";
 
+        /// <summary>
+        /// Contains data used to populate the the preview section of this result.
+        /// </summary>
         public PreviewInfo Preview { get; set; } = PreviewInfo.Default;
 
         /// <summary>
-        /// Info of the preview image.
+        /// Info of the preview section of a <see cref="Result"/>
         /// </summary>
         public record PreviewInfo
         {
@@ -241,13 +251,28 @@ namespace Flow.Launcher.Plugin
             /// Full image used for preview panel
             /// </summary>
             public string PreviewImagePath { get; set; }
+
             /// <summary>
             /// Determines if the preview image should occupy the full width of the preview panel.
             /// </summary>
             public bool IsMedia { get; set; }
+
+            /// <summary>
+            /// Result description text that is shown at the bottom of the preview panel.
+            /// </summary>
+            /// <remarks>
+            /// When a value is not set, the <see cref="SubTitle"/> will be used.
+            /// </remarks>
             public string Description { get; set; }
+
+            /// <summary>
+            /// Delegate to get the preview panel's image
+            /// </summary>
             public IconDelegate PreviewDelegate { get; set; }
 
+            /// <summary>
+            /// Default instance of <see cref="PreviewInfo"/>
+            /// </summary>
             public static PreviewInfo Default { get; } = new()
             {
                 PreviewImagePath = null,