merge PR #2193: Update Plugin documentation

Author: JohnTheGr8

Flow.Launcher.Plugin/ActionContext.cs

@@ -2,18 +2,47 @@
 
 namespace Flow.Launcher.Plugin
 {
+    /// <summary>
+    /// Context provided as a parameter when invoking a
+    /// <see cref="Result.Action"/> or <see cref="Result.AsyncAction"/>
+    /// </summary>
     public class ActionContext
     {
+        /// <summary>
+        /// Contains the press state of certain special keys.
+        /// </summary>
         public SpecialKeyState SpecialKeyState { get; set; }
     }
 
+    /// <summary>
+    /// Contains the press state of certain special keys.
+    /// </summary>
     public class SpecialKeyState
     {
+        /// <summary>
+        /// True if the Ctrl key is pressed.
+        /// </summary>
         public bool CtrlPressed { get; set; }
+
+        /// <summary>
+        /// True if the Shift key is pressed.
+        /// </summary>
         public bool ShiftPressed { get; set; }
+
+        /// <summary>
+        /// True if the Alt key is pressed.
+        /// </summary>
         public bool AltPressed { get; set; }
+
+        /// <summary>
+        /// True if the Windows key is pressed.
+        /// </summary>
         public bool WinPressed { get; set; }
 
+        /// <summary>
+        /// Get this object represented as a <see cref="ModifierKeys"/> flag combination.
+        /// </summary>
+        /// <returns></returns>
         public ModifierKeys ToModifierKeys()
         {
             return (CtrlPressed ? ModifierKeys.Control : ModifierKeys.None) |

Flow.Launcher.Plugin/Flow.Launcher.Plugin.csproj

@@ -26,6 +26,7 @@
     <PackageTags>flowlauncher</PackageTags>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
+    <PackageReadmeFile>Readme.md</PackageReadmeFile>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(APPVEYOR)' == 'True'">
@@ -56,7 +57,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <None Include="README.md" />
+    <None Include="Readme.md" Pack="true" PackagePath="\"/>
     <None Include="FodyWeavers.xml" />
   </ItemGroup>
 

Flow.Launcher.Plugin/Interfaces/IContextMenu.cs

@@ -1,9 +1,18 @@
-using System.Collections.Generic;
+using System.Collections.Generic;
 
 namespace Flow.Launcher.Plugin
 {
+    /// <summary>
+    /// Adds support for presenting additional options for a given <see cref="Result"/> from a context menu.
+    /// </summary>
     public interface IContextMenu : IFeatures
     {
+        /// <summary>
+        /// Load context menu items for the given result.
+        /// </summary>
+        /// <param name="selectedResult">
+        /// The <see cref="Result"/> for which the user has activated the context menu.
+        /// </param>
         List<Result> LoadContextMenus(Result selectedResult);
     }
 }

Flow.Launcher.Plugin/Interfaces/IPluginI18n.cs

@@ -1,4 +1,4 @@
-using System.Globalization;
+using System.Globalization;
 
 namespace Flow.Launcher.Plugin
 {
@@ -7,8 +7,14 @@ namespace Flow.Launcher.Plugin
     /// </summary>
     public interface IPluginI18n : IFeatures
     {
+        /// <summary>
+        /// Get a localised version of the plugin's title
+        /// </summary>
         string GetTranslatedPluginTitle();
 
+        /// <summary>
+        /// Get a localised version of the plugin's description
+        /// </summary>
         string GetTranslatedPluginDescription();
 
         /// <summary>

Flow.Launcher.Plugin/Interfaces/ISavable.cs

@@ -1,12 +1,18 @@
-namespace Flow.Launcher.Plugin
+namespace Flow.Launcher.Plugin
 {
     /// <summary>
-    /// Save addtional plugin data. Inherit this interface if additional data e.g. cache needs to be saved,
-    /// Otherwise if LoadSettingJsonStorage or SaveSettingJsonStorage has been callded,
-    /// plugin settings will be automatically saved (see Flow.Launcher/PublicAPIInstance.SavePluginSettings) by Flow
+    /// Inherit this interface if additional data e.g. cache needs to be saved.
     /// </summary>
+    /// <remarks>
+    /// For storing plugin settings, prefer <see cref="IPublicAPI.LoadSettingJsonStorage{T}"/>
+    /// or <see cref="IPublicAPI.SaveSettingJsonStorage{T}"/>. 
+    /// Once called, your settings will be automatically saved by Flow.
+    /// </remarks>
     public interface ISavable : IFeatures
     {
+        /// <summary>
+        /// Save additional plugin data, such as cache.
+        /// </summary>
         void Save();
     }
 }

Flow.Launcher.Plugin/PluginInitContext.cs

@@ -1,5 +1,8 @@
 namespace Flow.Launcher.Plugin
 {
+    /// <summary>
+    /// Carries data passed to a plugin when it gets initialized.
+    /// </summary>
     public class PluginInitContext
     {
         public PluginInitContext()
@@ -12,6 +15,9 @@ public PluginInitContext(PluginMetadata currentPluginMetadata, IPublicAPI api)
             API = api;
         }
 
+        /// <summary>
+        /// The metadata of the plugin being initialized.
+        /// </summary>
         public PluginMetadata CurrentPluginMetadata { get; internal set; }
 
         /// <summary>

Flow.Launcher.Plugin/Query.cs

@@ -36,13 +36,14 @@ public Query(string rawQuery, string search, string[] terms, string[] searchTerm
         /// <summary>
         /// Search part of a query.
         /// This will not include action keyword if exclusive plugin gets it, otherwise it should be same as RawQuery.
-        /// Since we allow user to switch a exclusive plugin to generic plugin, 
+        /// Since we allow user to switch a exclusive plugin to generic plugin,
         /// so this property will always give you the "real" query part of the query
         /// </summary>
         public string Search { get; internal init; }
 
         /// <summary>
         /// The search string split into a string array.
+        /// Does not include the <see cref="ActionKeyword"/>.
         /// </summary>
         public string[] SearchTerms { get; init; }
 
@@ -59,6 +60,7 @@ public Query(string rawQuery, string search, string[] terms, string[] searchTerm
 
         [Obsolete("Typo")]
         public const string TermSeperater = TermSeparator;
+
         /// <summary>
         /// User can set multiple action keywords seperated by ';'
         /// </summary>
@@ -69,15 +71,22 @@ public Query(string rawQuery, string search, string[] terms, string[] searchTerm
 
 
         /// <summary>
-        /// '*' is used for System Plugin
+        /// Wildcard action keyword. Plugins using this value will be queried on every search.
         /// </summary>
         public const string GlobalPluginWildcardSign = "*";
 
+        /// <summary>
+        /// The action keyword part of this query.
+        /// For global plugins this value will be empty.
+        /// </summary>
         public string ActionKeyword { get; init; }
 
         /// <summary>
-        /// Return first search split by space if it has
+        /// 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>
         public string FirstSearch => SplitSearch(0);
 
         private string _secondToEndSearch;
@@ -88,20 +97,27 @@ public Query(string rawQuery, string search, string[] terms, string[] searchTerm
         public string SecondToEndSearch => SearchTerms.Length > 1 ? (_secondToEndSearch ??= string.Join(' ', SearchTerms[1..])) : "";
 
         /// <summary>
-        /// Return second search split by space if it has
+        /// Splits <see cref="SearchTerms"/> by spaces and returns the second item.
         /// </summary>
+        /// <remarks>
+        /// returns an empty string when <see cref="SearchTerms"/> does not have enough items.
+        /// </remarks>
         public string SecondSearch => SplitSearch(1);
 
         /// <summary>
-        /// Return third search split by space if it has
+        /// Splits <see cref="SearchTerms"/> by spaces and returns the third item.
         /// </summary>
+        /// <remarks>
+        /// returns an empty string when <see cref="SearchTerms"/> does not have enough items.
+        /// </remarks>
         public string ThirdSearch => SplitSearch(2);
 
         private string SplitSearch(int index)
         {
             return index < SearchTerms.Length ? SearchTerms[index] : string.Empty;
         }
 
+        /// <inheritdoc />
         public override string ToString() => RawQuery;
     }
 }

Flow.Launcher.Plugin/README.md

@@ -1,6 +1,7 @@
-What does Flow.Launcher.Plugin do?
-====
+Reference this package to develop a plugin for [Flow Launcher](https://github.com/Flow-Launcher/Flow.Launcher).
 
-* Defines base objects and interfaces for plugins
-* Plugin authors making C# plugins should reference this DLL via nuget
-* Contains commands and models that can be used by plugins
+Useful links:
+
+* [General plugin development guide](https://www.flowlauncher.com/docs/#/plugin-dev)
+* [.Net plugin development guide](https://www.flowlauncher.com/docs/#/develop-dotnet-plugins)
+* [Package API Reference](https://www.flowlauncher.com/docs/#/API-Reference/Flow.Launcher.Plugin)