Update docs

Author: hishamco

src/OrchardCore.Modules/OrchardCore.Users/Services/SetupEventHandler.cs

@@ -6,11 +6,8 @@
 namespace OrchardCore.Users.Services;
 
 /// <summary>
-/// Represents a setup event handler, which allows you to execute a code during the setup process.
+/// Handles setup events by creating the initial administrator user during application setup.
 /// </summary>
-/// <remarks>
-/// During setup, creates the admin user account.
-/// </remarks>
 public class SetupEventHandler : ISetupEventHandler
 {
     private readonly IUserService _userService;
@@ -20,6 +17,7 @@ public SetupEventHandler(IUserService userService)
         _userService = userService;
     }
 
+    /// <inheritdoc/>
     public Task SetupAsync(SetupContext context)
     {
         var user = new User

src/OrchardCore/OrchardCore.Setup.Abstractions/Events/ISetupEventHandler.cs

@@ -3,26 +3,33 @@
 namespace OrchardCore.Setup.Events;
 
 /// <summary>
-/// Represents a contract for handling setup events.
+/// Defines methods for handling setup events, including performing setup operations and marking their success or
+/// failure.
 /// </summary>
+/// <remarks>Implement this interface to provide custom logic for setup processes that require asynchronous
+/// handling of configuration, initialization, or error reporting. Methods are designed to be called during the setup
+/// lifecycle to signal progress or outcome. Implementations should ensure thread safety if setup events may be
+/// triggered concurrently.
+/// </remarks>
 public interface ISetupEventHandler
 {
     /// <summary>
-    /// Called during the process of setting up a new tenant.
+    /// Performs asynchronous setup operations using the specified context.
     /// </summary>
-    /// <param name="context"></param>
-    /// <returns></returns>
+    /// <param name="context">An object that provides configuration and state information required for the setup process. Cannot be null.</param>
+    /// <returns>A task that represents the asynchronous setup operation.</returns>
     Task SetupAsync(SetupContext context) => Task.CompletedTask;
 
     /// <summary>
-    /// Called when a tenant fails to setup.
+    /// Marks the setup operation as failed within the provided context.
     /// </summary>
-    /// <returns></returns>
+    /// <param name="context">The setup context in which the failure is recorded. Cannot be null.</param>
+    /// <returns>A completed task that represents the asynchronous operation.</returns>
     Task FailedAsync(SetupContext context) => Task.CompletedTask;
 
     /// <summary>
-    /// Called when a new tenant is successfully setup.
+    /// Returns a completed task that represents a successful asynchronous operation.
     /// </summary>
-    /// <returns></returns>
+    /// <returns>A <see cref="Task"/> that has already completed successfully.</returns>
     Task SucceededAsync() => Task.CompletedTask;
 }

src/OrchardCore/OrchardCore.Setup.Abstractions/Services/ISetupService.cs

@@ -3,20 +3,28 @@
 namespace OrchardCore.Setup.Services;
 
 /// <summary>
-/// Represents a contract for the setup service.
+/// Provides methods for retrieving setup recipes and performing tenant setup operations.
 /// </summary>
+/// <remarks>Implementations of this interface enable the management of application setup processes, including
+/// listing available setup recipes and executing tenant setup. Methods are asynchronous and intended for use in
+/// scenarios where application initialization or configuration is required.
+/// </remarks>
 public interface ISetupService
 {
     /// <summary>
-    /// Gets the setup recipes.
+    /// Asynchronously retrieves a collection of setup recipe descriptors available for configuration.
     /// </summary>
-    /// <returns>A list of <see cref="RecipeDescriptor"/>s.</returns>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an enumerable collection of <see
+    /// cref="RecipeDescriptor"/> objects describing available setup recipes. The collection will be empty if no setup
+    /// recipes are found.</returns>
     Task<IEnumerable<RecipeDescriptor>> GetSetupRecipesAsync();
 
     /// <summary>
-    /// Set up the tenant.
+    /// Initializes the setup process asynchronously using the specified context and returns a status message upon
+    /// completion.
     /// </summary>
-    /// <param name="context">The <see cref="SetupContext"/>.</param>
-    /// <returns> A GUID string the represents a setup execution identifier.</returns>
+    /// <param name="context">The setup context containing configuration and parameters required for initialization. Cannot be null.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains a string describing the outcome of
+    /// the setup process.</returns>
     Task<string> SetupAsync(SetupContext context);
 }

src/OrchardCore/OrchardCore.Setup.Abstractions/Services/ISetupUserIdGenerator.cs

@@ -1,12 +1,18 @@
 namespace OrchardCore.Setup.Services;
 
 /// <summary>
-/// Represents a contract for generating identifiers for setup users.
+/// Defines a contract for generating unique identifier strings for use as keys, tokens, or other distinct values.
 /// </summary>
+/// <remarks>Implementations may generate identifiers using different algorithms or formats. The generated
+/// identifier is intended to be unique within the context of the application or system. This interface is typically
+/// used during setup or initialization processes where a reliable, non-colliding identifier is required.</remarks>
 public interface ISetupUserIdGenerator
 {
     /// <summary>
-    /// Generates a unique identifier for the setup user.
+    /// Generates a unique identifier string suitable for use as a key or token.
     /// </summary>
+    /// <returns>A string containing a unique identifier. The format and length of the identifier may vary depending on the
+    /// implementation.
+    /// </returns>
     string GenerateUniqueId();
 }

src/OrchardCore/OrchardCore.Setup.Core/Services/SetupService.cs

@@ -19,7 +19,8 @@
 namespace OrchardCore.Setup.Services;
 
 /// <summary>
-/// Represents a setup service, which is responsible for setting up the tenant.
+/// Provides services for retrieving setup recipes and performing application setup operations, including initializing
+/// tenants and configuring the database during the setup process.
 /// </summary>
 public class SetupService : ISetupService
 {

src/OrchardCore/OrchardCore.Setup.Core/Services/SetupUserIdGenerator.cs

@@ -1,14 +1,13 @@
 using OrchardCore.Entities;
-using OrchardCore.Recipes.Models;
 
 namespace OrchardCore.Setup.Services;
 
 /// <summary>
-/// Represents a class that generates unique user id for setup that will be stored in <see cref="RecipeEnvironmentFeature"/>.
+/// Provides functionality to generate unique identifiers for setup users using a specified ID generator implementation.
 /// </summary>
-/// <remarks>
-/// The generated user id will be used to keep track the admin user id during the setup process.
-/// </remarks>
+/// <remarks>This class acts as an adapter for the <see cref="IIdGenerator"/> interface, allowing setup user IDs
+/// to be generated consistently across different environments. Thread safety and uniqueness guarantees depend on the
+/// underlying <see cref="IIdGenerator"/> implementation.</remarks>
 public class SetupUserIdGenerator : ISetupUserIdGenerator
 {
     private readonly IIdGenerator _generator;