Misc, documentation day!

ArchiSteamFarm/Plugins/Interfaces/IASF.cs

@@ -29,6 +29,11 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to easily register your own data structures upon ASF initialization. This is especially useful if you want to register those based on the ASF's global config.
+/// </summary>
+/// <remarks>If your logic doesn't require ASF settings, you can consider using core <see cref="IPlugin.OnLoaded" /> method instead. Implementing this interface might still make sense, since it happens later during ASF initialization and provides more available data structures.</remarks>
 [PublicAPI]
 public interface IASF : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBot.cs

@@ -27,6 +27,11 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to register core settings-independent structures on per-bot basis.
+/// </summary>
+/// <remarks>If your logic requires bot's settings, consider implementing <see cref="IBotModules" /> instead. Implementing this interface might still make sense, e.g. for disposal of the structures upon <see cref="OnBotDestroy" />.</remarks>
 [PublicAPI]
 public interface IBot : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotCardsFarmerInfo.cs

@@ -23,10 +23,15 @@
 
 using System.Threading.Tasks;
 using ArchiSteamFarm.Steam;
+using ArchiSteamFarm.Steam.Cards;
 using JetBrains.Annotations;
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to receive updates in regards to ASF's <see cref="CardsFarmer" /> module, in particular events related to its state.
+/// </summary>
 [PublicAPI]
 public interface IBotCardsFarmerInfo : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotCommand2.cs

@@ -28,6 +28,11 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to react to each command received by ASF, in particular, implementing your own custom commands.
+/// </summary>
+/// <remarks>This is used for commands, irrelevant of their origin (IPC, console, Steam). If you want to grab non-command Steam messages, check <see cref="IBotMessage" /> interface instead.</remarks>
 [PublicAPI]
 public interface IBotCommand2 : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotConnection.cs

@@ -28,6 +28,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to monitor Bot's connection with the Steam network, in particular when it goes online and offline.
+/// </summary>
 [PublicAPI]
 public interface IBotConnection : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotCustomMachineInfoProvider.cs

@@ -28,6 +28,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to provide low-level machine info provider that will be used for providing core information during Steam login procedure.
+/// </summary>
 [PublicAPI]
 public interface IBotCustomMachineInfoProvider : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotFriendRequest.cs

@@ -27,6 +27,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to handle friend requests on the Steam platform.
+/// </summary>
 [PublicAPI]
 public interface IBotFriendRequest : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotIdentity.cs

@@ -28,6 +28,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to discover core properties of your bot's identity, upon logging in to the Steam network.
+/// </summary>
 [PublicAPI]
 public interface IBotIdentity : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotMessage.cs

@@ -28,6 +28,11 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to react to each message received on the Steam platform.
+/// </summary>
+/// <remarks>This is used for Steam messages exclusively, that are not ASF commands. If you want to grab the commands, check <see cref="IBotCommand2" /> interface instead.</remarks>
 [PublicAPI]
 public interface IBotMessage : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotModules.cs

@@ -30,6 +30,11 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to easily register your own custom modules on per-bot basis. This is especially useful if you want to register those based on the bot's config.
+/// </summary>
+/// <remarks>If your modules do not depend on bot's settings, you can consider implementing <see cref="IBot" /> interface instead. Even without that requirement, implementing that interface might still make sense, e.g. for disposal of the structures in <see cref="IBot.OnBotDestroy" />.</remarks>
 [PublicAPI]
 public interface IBotModules : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotSteamClient.cs

@@ -29,6 +29,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to register your own SteamKit2 message handlers, which means controlling the traffic that comes from the Steam network.
+/// </summary>
 [PublicAPI]
 public interface IBotSteamClient : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotTradeOffer.cs

@@ -28,6 +28,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows your plugin to implement custom logic for accepting trades that ASF isn't willing to handle itself.
+/// </summary>
 [PublicAPI]
 public interface IBotTradeOffer : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotTradeOfferResults.cs

@@ -29,6 +29,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to receive information about all processed trades, in particular if you want to fire some logic based on trade offers being handled.
+/// </summary>
 [PublicAPI]
 public interface IBotTradeOfferResults : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotUserNotifications.cs

@@ -29,6 +29,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to receive Steam notifications transmitted over the network.
+/// </summary>
 [PublicAPI]
 public interface IBotUserNotifications : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IBotsComparer.cs

@@ -26,6 +26,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to change the default string comparers used across ASF.
+/// </summary>
 [PublicAPI]
 public interface IBotsComparer : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/ICrossProcessSemaphoreProvider.cs

@@ -27,6 +27,11 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to provide custom cross-process semaphore, which is used for synchronizing multiple ASF instances with their limiters.
+///     Custom cross-process semaphore might be useful if you wanted to extend cross-process semaphore offered by ASF, e.g. by utilizing remote-oriented tools like redis and allowing ASF instances over several different machines to synchronize with each other.
+/// </summary>
 [PublicAPI]
 public interface ICrossProcessSemaphoreProvider : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IPlugin.cs

@@ -29,6 +29,9 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <summary>
+///     Implementing this interface allows you to register your plugin in ASF, in turn providing you a way to implement your own custom logic.
+/// </summary>
 [PublicAPI]
 public interface IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IPluginUpdates.cs

@@ -28,6 +28,7 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
 /// <summary>
 ///     Implementing this interface allows you to provide custom logic for updating your plugin to newer version.
 ///     Plugin updates are happening on usual basis per configuration of auto-updates from ASF, as well as other triggers such as update command.

ArchiSteamFarm/Plugins/Interfaces/ISteamPICSChanges.cs

@@ -28,6 +28,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to be notified about PICS changes, which is Steam mechanism for broadcasting app and package updates.
+/// </summary>
 [PublicAPI]
 public interface ISteamPICSChanges : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IUpdateAware.cs

@@ -27,6 +27,10 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
+/// <summary>
+///     Implementing this interface allows you to be aware of ASF updates and execute appropriate logic that you need to happen before/after such update happens.
+/// </summary>
 [PublicAPI]
 public interface IUpdateAware : IPlugin {
 	/// <summary>

ArchiSteamFarm/Plugins/Interfaces/IWebInterface.cs

@@ -25,18 +25,23 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
 /// <summary>
 ///     Implementing this interface allows you to provide your own (custom) web interface files that will be exposed by standard ASF's IPC interface. In order to achieve that, you must include a directory with your web interface (html, css, js) files together with your plugin's DLL assembly, then specify path to it in <see cref="PhysicalPath" /> and finally the path under which you want to host those files in <see cref="WebPath" />.
 /// </summary>
 public interface IWebInterface : IPlugin {
 	/// <summary>
 	///     Specifies physical path to static WWW files provided by the plugin. Can be either relative to plugin's assembly location, or absolute. Default value of "www" assumes that you ship "www" directory together with your plugin's main DLL assembly, similar to ASF.
 	/// </summary>
+	/// <example>www</example>
+	/// <remarks>You'll need to ship this folder together with your plugin for the interface to work.</remarks>
 	string PhysicalPath => "www";
 
 	/// <summary>
-	///     Specifies web path (address) under which ASF should host your static WWW files in <see cref="PhysicalPath" /> directory. Default value of "/" allows you to override default ASF files and gives you full flexibility in your <see cref="PhysicalPath" /> directory. However, you can instead host your files under some other fixed location specified here, such as "/MyPlugin".
+	///     Specifies web path (address) under which ASF should host your static WWW files in <see cref="PhysicalPath" /> directory. Default value of "/" allows you to override default ASF files and gives you full flexibility in your <see cref="PhysicalPath" /> directory. However, you can instead host your files under some other fixed location specified here, such as "/MyPlugin", which is especially useful if you want to have your own default index.html in addition to the one provided by us (ASF-ui).
 	/// </summary>
+	/// <example>/MyPlugin</example>
+	/// <remarks>If you're using path other than default, ensure it does NOT end with a slash.</remarks>
 	[JsonInclude]
 	string WebPath => "/";
 }

ArchiSteamFarm/Plugins/Interfaces/IWebServiceProvider.cs

@@ -27,19 +27,20 @@
 
 namespace ArchiSteamFarm.Plugins.Interfaces;
 
+/// <inheritdoc />
 /// <summary>
 ///     Implementing this interface allows you to provide your own additional services and middlewares for IPC endpoints - Use with caution!
 /// </summary>
 [PublicAPI]
-public interface IWebServiceProvider {
+public interface IWebServiceProvider : IPlugin {
 	/// <summary>
-	///     ASF will call this method during configuration of the IPC endpoints
+	///     ASF will call this method during configuration of the IPC endpoints.
 	/// </summary>
 	/// <param name="app">Application builder related to this callback.</param>
 	void OnConfiguringEndpoints(IApplicationBuilder app);
 
 	/// <summary>
-	///     ASF will call this method during configuration of the IPC services
+	///     ASF will call this method during configuration of the IPC services.
 	/// </summary>
 	/// <param name="services">Service collection related to this callback.</param>
 	void OnConfiguringServices(IServiceCollection services);