Add xmldocs for the most important dashboard types

Author: odinserj

src/Hangfire.Core/Dashboard/DashboardContext.cs

@@ -20,38 +20,94 @@
 
 namespace Hangfire.Dashboard
 {
+    /// <summary>
+    /// Provides the context for the Dashboard UI. This class serves as a base class for specific web application frameworks,
+    /// such as ASP.NET Core or OWIN, and is accessible from different Dashboard UI request dispatchers (please see
+    /// <see cref="IDashboardDispatcher"/>), like pages or other endpoints.
+    /// </summary>
+    /// <remarks>
+    /// The <see cref="DashboardContext"/> class encapsulates the HTTP request and response details,
+    /// along with settings and services necessary to process dashboard requests.
+    /// It provides an abstraction that allows easy integration with various web frameworks by inheriting from this class
+    /// and implementing the specific behavior required for those frameworks.
+    /// </remarks>
     public abstract class DashboardContext
     {
         private readonly Lazy<bool> _isReadOnlyLazy;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DashboardContext"/> class.
+        /// </summary>
+        /// <param name="storage">The job storage used by the Dashboard UI.</param>
+        /// <param name="options">The options for configuring the Dashboard UI.</param>
+        /// <exception cref="ArgumentNullException">
+        /// Thrown when <paramref name="storage"/> or <paramref name="options"/> is null.
+        /// </exception>
         protected DashboardContext([NotNull] JobStorage storage, [NotNull] DashboardOptions options)
         {
-            if (storage == null) throw new ArgumentNullException(nameof(storage));
-            if (options == null) throw new ArgumentNullException(nameof(options));
+            Storage = storage ?? throw new ArgumentNullException(nameof(storage));
+            Options = options ?? throw new ArgumentNullException(nameof(options));
 
-            Storage = storage;
-            Options = options;
-            _isReadOnlyLazy = new Lazy<bool>(() => options.IsReadOnlyFunc(this));
+            _isReadOnlyLazy = new Lazy<bool>(() => Options.IsReadOnlyFunc(this));
         }
 
+        /// <summary>
+        /// Gets the <see cref="JobStorage"/> instance used by the Dashboard UI.
+        /// </summary>
         public JobStorage Storage { get; }
+
+        /// <summary>
+        /// Gets the <see cref="DashboardOptions"/> for configuring the Dashboard UI.
+        /// </summary>
         public DashboardOptions Options { get; }
 
+        /// <summary>
+        /// Gets or sets the URI match information passed from the configured <c>pathTemplate</c>
+        /// when defining a route in the <see cref="DashboardRoutes"/> class.
+        /// </summary>
         public Match UriMatch { get; set; }
-        
+
+        /// <summary>
+        /// Gets the <see cref="DashboardRequest"/> metadata.
+        /// Used by request dispatchers (please see <see cref="IDashboardDispatcher"/>) to provide request information.
+        /// </summary>
         public DashboardRequest Request { get; protected set; }
+
+        /// <summary>
+        /// Gets the <see cref="DashboardResponse"/> metadata.
+        /// Used by request dispatchers (please see <see cref="IDashboardDispatcher"/>) to send response information.
+        /// </summary>
         public DashboardResponse Response { get; protected set; }
 
+        /// <summary>
+        /// Gets a value indicating whether the Dashboard UI is in read-only mode to possibly
+        /// hide elements that modify the <see cref="JobStorage"/> instance's data.
+        /// </summary>
         public bool IsReadOnly => _isReadOnlyLazy.Value;
 
+        /// <summary>
+        /// Gets or sets the anti-forgery header value.
+        /// </summary>
         public string AntiforgeryHeader { get; set; }
+
+        /// <summary>
+        /// Gets or sets the anti-forgery token value.
+        /// </summary>
         public string AntiforgeryToken { get; set; }
 
+        /// <summary>
+        /// Gets the background job client for the current <see cref="JobStorage"/> instance.
+        /// </summary>
+        /// <returns>An instance of <see cref="IBackgroundJobClient"/>.</returns>
         public virtual IBackgroundJobClient GetBackgroundJobClient()
         {
             return new BackgroundJobClient(Storage);
         }
 
+        /// <summary>
+        /// Gets the recurring job manager for the current <see cref="JobStorage"/> instance.
+        /// </summary>
+        /// <returns>An instance of <see cref="IRecurringJobManager"/>.</returns>
         public virtual IRecurringJobManager GetRecurringJobManager()
         {
             return new RecurringJobManager(

src/Hangfire.Core/Dashboard/DashboardRequest.cs

@@ -18,16 +18,57 @@
 
 namespace Hangfire.Dashboard
 {
+    /// <summary>
+    /// Provides the request details for the Dashboard UI. This class serves as an abstraction for HTTP requests
+    /// and is used within <see cref="IDashboardDispatcher"/> implementations to access request information.
+    /// </summary>
+    /// <remarks>
+    /// The <see cref="DashboardRequest"/> class encapsulates the HTTP request details, providing properties to access
+    /// the method, path, base path, IP addresses, and query or form values.
+    /// This allows for a consistent way to handle requests across different web frameworks.
+    /// </remarks>
     public abstract class DashboardRequest
     {
+        /// <summary>
+        /// Gets the HTTP method of the request like <c>"GET"</c> or <c>"POST"</c>, that can
+        /// be checked for equality by using the <see cref="System.StringComparison.OrdinalIgnoreCase"/> comparer. 
+        /// </summary>
         public abstract string Method { get; }
+
+        /// <summary>
+        /// Gets the request path for the current request that doesn't include the <see cref="DashboardOptions.PrefixPath"/>,
+        /// like <c>"/jobs/enqueued"</c>.
+        /// </summary>
         public abstract string Path { get; }
+
+        /// <summary>
+        /// Gets the base path for the request configured in the request middleware, usually useful
+        /// to reconstruct full URIs like for link generation.
+        /// </summary>
         public abstract string PathBase { get; }
 
+        /// <summary>
+        /// Gets the local IP address from which the request originated.
+        /// </summary>
         public abstract string LocalIpAddress { get; }
+
+        /// <summary>
+        /// Gets the remote IP address from which the request originated.
+        /// </summary>
         public abstract string RemoteIpAddress { get; }
 
+        /// <summary>
+        /// Gets the value of a specific query string parameter.
+        /// </summary>
+        /// <param name="key">The key of the query string parameter.</param>
+        /// <returns>The value of the query string parameter.</returns>
         public abstract string GetQuery(string key);
+
+        /// <summary>
+        /// Gets the values of a specific form parameter asynchronously, reading the request body if it's a form.
+        /// </summary>
+        /// <param name="key">The key of the form parameter.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains the list of values for the form parameter.</returns>
         public abstract Task<IList<string>> GetFormValuesAsync(string key);
     }
 }

src/Hangfire.Core/Dashboard/DashboardResponse.cs

@@ -19,14 +19,47 @@
 
 namespace Hangfire.Dashboard
 {
+    /// <summary>
+    /// Provides the response details for the Dashboard UI. This class serves as an abstraction for HTTP responses
+    /// and is used within <see cref="IDashboardDispatcher"/> implementations to send response information.
+    /// </summary>
+    /// <remarks>
+    /// The <see cref="DashboardResponse"/> class encapsulates the HTTP response details, providing properties and methods
+    /// to set the content type, status code, body, and expiration of the response.
+    /// This allows for a consistent way to handle responses across different web frameworks.
+    /// </remarks>
     public abstract class DashboardResponse
     {
+        /// <summary>
+        /// Gets or sets the content type of the response like <c>"application/json"</c>.
+        /// </summary>
+        /// <value>The content type of the response.</value>
         public abstract string ContentType { get; set; }
+
+        /// <summary>
+        /// Gets or sets the HTTP status code of the response like <c>200</c>.
+        /// </summary>
+        /// <value>The status code of the response.</value>
         public abstract int StatusCode { get; set; }
 
+        /// <summary>
+        /// Gets the response body stream, most of the time it's better to use the
+        /// <see cref="WriteAsync"/> method instead for text data.
+        /// </summary>
+        /// <value>The response body stream.</value>
         public abstract Stream Body { get; }
 
+        /// <summary>
+        /// Sets the expiration time for the response.
+        /// </summary>
+        /// <param name="value">The expiration time, or <c>null</c> to remove the expiration header.</param>
         public abstract void SetExpire(DateTimeOffset? value);
+
+        /// <summary>
+        /// Writes the specified text to the response body asynchronously.
+        /// </summary>
+        /// <param name="text">The text to write to the response body.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
         public abstract Task WriteAsync(string text);
     }
 }

src/Hangfire.Core/Dashboard/DashboardRoutes.cs

@@ -22,6 +22,19 @@
 
 namespace Hangfire.Dashboard
 {
+    /// <summary>
+    /// Provides the routing mechanisms for the Dashboard UI. This class is used to register custom
+    /// request dispatchers, allowing developers to write extensions for the Dashboard UI, such as
+    /// custom pages, API endpoints or adding custom JavaScript or CSS files.
+    /// </summary>
+    /// <remarks>
+    /// The <see cref="DashboardRoutes"/> class contains a collection of routes that the Dashboard UI uses to dispatch requests to handlers.
+    /// Developers can use this class to add custom scripts, stylesheets, and register custom routes for extending the dashboard functionality.
+    /// 
+    /// To add a custom route, use the <see cref="DashboardRoutes.Routes"/> property which is an instance of <see cref="RouteCollection"/>.
+    /// </remarks>
+    /// <seealso cref="RouteCollection"/>
+    /// <seealso cref="IDashboardDispatcher"/>
     public static class DashboardRoutes
     {
         private static readonly List<Tuple<Assembly, string>> JavaScripts = new List<Tuple<Assembly, string>>();
@@ -179,8 +192,22 @@ static DashboardRoutes()
             #endregion
         }
 
+        /// <summary>
+        /// Gets the collection of routes for the Dashboard UI. Use this property to register
+        /// custom request dispatchers.
+        /// </summary>
         public static RouteCollection Routes { get; }
 
+        /// <summary>
+        /// Adds a stylesheet resource embedded into the given assembly to be included in the dashboard.
+        /// </summary>
+        /// <remarks>
+        /// The specified resource should be an embedded resource file within the referenced assembly.
+        /// You can discover embedded resource names by calling the <c>assembly.GetManifestResourceNames()</c> method.
+        /// </remarks>
+        /// <param name="assembly">The assembly containing the embedded stylesheet resource.</param>
+        /// <param name="resource">The name of the stylesheet embedded resource.</param>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="assembly"/> or <paramref name="resource"/> is <c>null</c>.</exception>
         public static void AddStylesheet([NotNull] Assembly assembly, [NotNull] string resource)
         {
             if (assembly == null) throw new ArgumentNullException(nameof(assembly));
@@ -193,6 +220,17 @@ public static void AddStylesheet([NotNull] Assembly assembly, [NotNull] string r
             }
         }
 
+        /// <summary>
+        /// Adds a resource embedded into the given assembly that will only be included in the dashboard
+        /// when the <see cref="DashboardOptions.DarkModeEnabled"/> is set to <c>true</c>.
+        /// </summary>
+        /// <remarks>
+        /// The specified resource should be an embedded resource file within the referenced assembly.
+        /// You can discover embedded resource names by calling the <c>assembly.GetManifestResourceNames()</c> method.
+        /// </remarks>
+        /// <param name="assembly">The assembly containing the dark-mode stylesheet embedded resource.</param>
+        /// <param name="resource">The name of the dark-mode stylesheet embedded resource.</param>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="assembly"/> or <paramref name="resource"/> is <c>null</c>.</exception>
         public static void AddStylesheetDarkMode([NotNull] Assembly assembly, [NotNull] string resource)
         {
             if (assembly == null) throw new ArgumentNullException(nameof(assembly));
@@ -205,6 +243,16 @@ public static void AddStylesheetDarkMode([NotNull] Assembly assembly, [NotNull]
             }
         }
 
+        /// <summary>
+        /// Adds a JavaScript resource embedded into the given assembly to be included in the dashboard.
+        /// </summary>
+        /// <remarks>
+        /// The specified resource should be an embedded resource file within the referenced assembly.
+        /// You can discover embedded resource names by calling the <c>assembly.GetManifestResourceNames()</c> method.
+        /// </remarks>
+        /// <param name="assembly">The assembly containing the JavaScript embedded resource.</param>
+        /// <param name="resource">The name of the JavaScript embedded resource.</param>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="assembly"/> or <paramref name="resource"/> is <c>null</c>.</exception>
         public static void AddJavaScript([NotNull] Assembly assembly, [NotNull] string resource)
         {
             if (assembly == null) throw new ArgumentNullException(nameof(assembly));

src/Hangfire.Core/Dashboard/IDashboardDispatcher.cs

@@ -18,8 +18,26 @@
 
 namespace Hangfire.Dashboard
 {
+    /// <summary>
+    /// Defines the method for dispatching requests within the Dashboard UI.
+    /// Implementations of this interface handle incoming requests to the dashboard and produce appropriate responses.
+    /// </summary>
+    /// <remarks>
+    /// The <see cref="IDashboardDispatcher"/> interface is used to process requests in the Dashboard UI.
+    /// Implement this interface to handle custom routes and manage request processing logic.
+    /// 
+    /// To register custom dispatchers, use the <see cref="DashboardRoutes"/> class. The <c>DashboardRoutes.Routes</c>
+    /// property allows for adding new routes that the dashboard will use to dispatch requests to custom handlers.
+    /// </remarks>
+    /// <seealso cref="DashboardContext"/>
+    /// <seealso cref="DashboardRoutes"/>
     public interface IDashboardDispatcher
     {
+        /// <summary>
+        /// Processes the request within the provided <see cref="DashboardContext"/>.
+        /// </summary>
+        /// <param name="context">The context for the current dashboard request, containing information about the request and response.</param>
+        /// <returns>A task that represents the asynchronous dispatch operation.</returns>
         Task Dispatch([NotNull] DashboardContext context);
     }
 }