refactor: document all modules

Author: hamed-shirbandi

src/1-Libraries/Application/Dtos/CreateDemoThingDto.cs

@@ -5,16 +5,31 @@
 
 namespace CanBeYours.Application.Dtos;
 
+/// <summary>
+/// Data Transfer Object for creating a new DemoThing entity.
+/// This class demonstrates how to create DTOs with validation attributes and resource-based localization.
+/// The DemoThing functionality shown here is just an example to help you learn how to implement
+/// your own unique features into the current codebase.
+/// </summary>
 public class CreateDemoThingDto
 {
+    /// <summary>
+    /// The name of the demo thing. This field is required and will be displayed using localized resources.
+    /// </summary>
     [Display(Name = nameof(SharedResource.DemoThing_Name), ResourceType = typeof(SharedResource))]
     [Required(ErrorMessageResourceType = typeof(SharedResource), ErrorMessageResourceName = nameof(SharedResource.DemoThing_Name))]
     public string Name { get; set; }
 
+    /// <summary>
+    /// The description of the demo thing. This field is required and will be displayed using localized resources.
+    /// </summary>
     [Display(Name = nameof(SharedResource.DemoThing_Description), ResourceType = typeof(SharedResource))]
     [Required(ErrorMessageResourceType = typeof(SharedResource), ErrorMessageResourceName = nameof(SharedResource.DemoThing_Description))]
     public string Description { get; set; }
 
+    /// <summary>
+    /// The type of the demo thing. This field is required and determines the category of the demo thing.
+    /// </summary>
     [Display(Name = nameof(SharedResource.DemoThing_Type), ResourceType = typeof(SharedResource))]
     [Required(ErrorMessageResourceName = nameof(CoreResource.Required), ErrorMessageResourceType = typeof(CoreResource))]
     public DemoThingType Type { get; set; }

src/1-Libraries/Application/Dtos/GetDemoThingDto.cs

@@ -3,11 +3,38 @@
 
 namespace CanBeYours.Application.Dtos;
 
+/// <summary>
+/// Data Transfer Object for retrieving DemoThing entity data.
+/// This class demonstrates how to create response DTOs that extend base DTOs and include
+/// additional properties for display purposes.
+/// The DemoThing functionality shown here is just an example to help you learn how to implement
+/// your own unique features into the current codebase.
+/// </summary>
 public class GetDemoThingDto : GetEntityDto
 {
+    /// <summary>
+    /// The name of the demo thing for display purposes.
+    /// </summary>
     public string Name { get; set; }
+    
+    /// <summary>
+    /// The description of the demo thing for display purposes.
+    /// </summary>
     public string Description { get; set; }
+    
+    /// <summary>
+    /// The type/category of the demo thing.
+    /// </summary>
     public DemoThingType Type { get; set; }
+    
+    /// <summary>
+    /// The email address of the user who owns this demo thing.
+    /// This is populated by the service layer for display purposes.
+    /// </summary>
     public string UserEmail { get; set; }
+    
+    /// <summary>
+    /// The unique identifier of the user who owns this demo thing.
+    /// </summary>
     public string UserId { get; set; }
 }

src/1-Libraries/Application/Dtos/SearchDemoThingsInputDto.cs

@@ -3,12 +3,26 @@
 
 namespace CanBeYours.Application.Dtos;
 
+/// <summary>
+/// Data Transfer Object for search input parameters when searching DemoThing entities.
+/// This class demonstrates how to create search DTOs that extend base search DTOs and include
+/// custom filtering options with sensible defaults.
+/// The DemoThing functionality shown here is just an example to help you learn how to implement
+/// your own unique features into the current codebase.
+/// </summary>
 public class SearchDemoThingsInputDto : SearchInputDto
 {
+    /// <summary>
+    /// Initializes a new instance with a default page size of 5 records per page.
+    /// This demonstrates how to set sensible defaults for search parameters.
+    /// </summary>
     public SearchDemoThingsInputDto()
     {
         RecordsPerPage = 5;
     }
 
+    /// <summary>
+    /// Optional filter by demo thing type. When null, all types are included in the search.
+    /// </summary>
     public DemoThingType? Type { get; set; }
 }

src/1-Libraries/Application/Dtos/UpdateDemoThingDto.cs

@@ -5,16 +5,31 @@
 
 namespace CanBeYours.Application.Dtos;
 
+/// <summary>
+/// Data Transfer Object for updating an existing DemoThing entity.
+/// This class demonstrates how to create update DTOs with validation attributes and resource-based localization.
+/// The DemoThing functionality shown here is just an example to help you learn how to implement
+/// your own unique features into the current codebase.
+/// </summary>
 public class UpdateDemoThingDto
 {
+    /// <summary>
+    /// The new name for the demo thing. This field is required and will be displayed using localized resources.
+    /// </summary>
     [Display(Name = nameof(SharedResource.DemoThing_Name), ResourceType = typeof(SharedResource))]
     [Required(ErrorMessageResourceType = typeof(SharedResource), ErrorMessageResourceName = nameof(SharedResource.DemoThing_Name))]
     public string Name { get; set; }
 
+    /// <summary>
+    /// The new description for the demo thing. This field is required and will be displayed using localized resources.
+    /// </summary>
     [Display(Name = nameof(SharedResource.DemoThing_Description), ResourceType = typeof(SharedResource))]
     [Required(ErrorMessageResourceType = typeof(SharedResource), ErrorMessageResourceName = nameof(SharedResource.DemoThing_Description))]
     public string Description { get; set; }
 
+    /// <summary>
+    /// The new type for the demo thing. This field is required and determines the category of the demo thing.
+    /// </summary>
     [Display(Name = nameof(SharedResource.DemoThing_Type), ResourceType = typeof(SharedResource))]
     [Required(ErrorMessageResourceName = nameof(CoreResource.Required), ErrorMessageResourceType = typeof(CoreResource))]
     public DemoThingType Type { get; set; }

src/1-Libraries/Application/Exceptions/DemoThingApplicationExceptions.cs

@@ -8,8 +8,27 @@
 
 namespace CanBeYours.Application.Exceptions;
 
+/// <summary>
+/// Static factory class for creating application-specific exceptions related to DemoThing operations.
+/// This class demonstrates how to create custom exceptions with localized error messages and
+/// proper error handling patterns.
+/// The DemoThing functionality shown here is just an example to help you learn how to implement
+/// your own unique features into the current codebase.
+/// </summary>
 internal static class DemoThingApplicationExceptions
 {
+    /// <summary>
+    /// Creates an application exception when a demo thing is not found by the specified search key.
+    /// This method demonstrates how to create localized exceptions with placeholder values.
+    /// </summary>
+    /// <param name="searchedKey">The key that was used to search for the demo thing (e.g., ID, name)</param>
+    /// <returns>An application exception with localized error message</returns>
+    /// <example>
+    /// <code>
+    /// if (demoThing == null)
+    ///     throw DemoThingApplicationExceptions.DemoThingNotFound(id);
+    /// </code>
+    /// </example>
     public static ApplicationException DemoThingNotFound(string searchedKey)
     {
         return new ApplicationException(

src/1-Libraries/Application/Helpers/Permissions.cs

@@ -9,6 +9,10 @@ namespace CanBeYours.Application.Helpers;
 /// <summary>
 /// This class contains all permissions used in the application.
 /// They will be automatically registered in the database.
+/// This class demonstrates how to implement a permission system with reflection-based
+/// permission discovery and automatic database registration.
+/// The DemoThing functionality shown here is just an example to help you learn how to implement
+/// your own unique features into the current codebase.
 /// </summary>
 public static class Permissions
 {
@@ -25,7 +29,16 @@ public static class Demo
 
     /// <summary>
     /// Retrieves all permissions dynamically using reflection.
+    /// This method demonstrates how to automatically discover and register permissions
+    /// from nested static classes, making the permission system maintainable and extensible.
     /// </summary>
+    /// <returns>A collection of permission settings that can be registered in the database</returns>
+    /// <example>
+    /// <code>
+    /// var permissions = Permissions.GetPermissions();
+    /// // This will return permissions for Demo.DEMO_THINGS automatically
+    /// </code>
+    /// </example>
     public static IEnumerable<PermissionsSettings> GetPermissions()
     {
         var permissionsList = new List<PermissionsSettings>();

src/1-Libraries/Application/Services/DemoThings/DemoThingService.cs

@@ -9,26 +9,63 @@
 
 namespace CanBeYours.Application.Services.DemoThings;
 
+/// <summary>
+/// Application service for managing DemoThing entities.
+/// This class demonstrates how to implement application services that coordinate between
+/// different use cases and provide a clean API for the presentation layer.
+/// The DemoThing functionality shown here is just an example to help you learn how to implement
+/// your own unique features into the current codebase.
+/// </summary>
 internal class DemoThingService : ApplicationService, IDemoThingService
 {
+    /// <summary>
+    /// Initializes a new instance of the DemoThingService with the required dependencies.
+    /// </summary>
+    /// <param name="requestDispatcher">The request dispatcher for sending commands and queries</param>
     public DemoThingService(IRequestDispatcher requestDispatcher)
         : base(requestDispatcher) { }
 
+    /// <summary>
+    /// Retrieves a demo thing by its unique identifier.
+    /// This method demonstrates how to delegate to use cases using the request dispatcher.
+    /// </summary>
+    /// <param name="id">The unique identifier of the demo thing</param>
+    /// <returns>A result containing the demo thing data or an error</returns>
     public async Task<Result<GetDemoThingDto>> GetDemoThing(string id)
     {
         return await _requestDispatcher.SendQuery(new GetDemoThingRequest(id));
     }
 
+    /// <summary>
+    /// Creates a new demo thing with the specified data.
+    /// This method demonstrates how to delegate to use cases using the request dispatcher.
+    /// </summary>
+    /// <param name="input">The data for creating the new demo thing</param>
+    /// <returns>A result containing the command execution result or an error</returns>
     public async Task<Result<CommandResult>> CreateDemoThing(CreateDemoThingDto input)
     {
         return await _requestDispatcher.SendCommand(new CreateDemoThingRequest(input.Name, input.Description, input.Type));
     }
 
+    /// <summary>
+    /// Updates an existing demo thing with new data.
+    /// This method demonstrates how to delegate to use cases using the request dispatcher.
+    /// </summary>
+    /// <param name="id">The unique identifier of the demo thing to update</param>
+    /// <param name="input">The new data for the demo thing</param>
+    /// <returns>A result containing the command execution result or an error</returns>
     public async Task<Result<CommandResult>> UpdateDemoThing(string id, UpdateDemoThingDto input)
     {
         return await _requestDispatcher.SendCommand(new UpdateDemoThingRequest(id, input.Name, input.Description, input.Type));
     }
 
+    /// <summary>
+    /// Searches for demo things based on specified criteria.
+    /// This method demonstrates how to delegate to use cases using the request dispatcher
+    /// and map complex input parameters.
+    /// </summary>
+    /// <param name="input">The search criteria and pagination parameters</param>
+    /// <returns>A result containing the search results with pagination information</returns>
     public async Task<Result<SearchOutputDto<GetDemoThingDto>>> SearchDemoThings(SearchDemoThingsInputDto input)
     {
         return await _requestDispatcher.SendQuery(

src/1-Libraries/Application/Services/DemoThings/IDemoThingService.cs

@@ -4,10 +4,41 @@
 
 namespace CanBeYours.Application.Services.DemoThings;
 
+/// <summary>
+/// Service interface for managing DemoThing entities.
+/// This interface demonstrates how to define service contracts with proper return types
+/// and async operations following CQRS patterns.
+/// The DemoThing functionality shown here is just an example to help you learn how to implement
+/// your own unique features into the current codebase.
+/// </summary>
 public interface IDemoThingService
 {
+    /// <summary>
+    /// Retrieves a demo thing by its unique identifier.
+    /// </summary>
+    /// <param name="id">The unique identifier of the demo thing</param>
+    /// <returns>A result containing the demo thing data or an error</returns>
     Task<Result<GetDemoThingDto>> GetDemoThing(string id);
+    
+    /// <summary>
+    /// Creates a new demo thing with the specified data.
+    /// </summary>
+    /// <param name="input">The data for creating the new demo thing</param>
+    /// <returns>A result containing the command execution result or an error</returns>
     Task<Result<CommandResult>> CreateDemoThing(CreateDemoThingDto input);
+    
+    /// <summary>
+    /// Updates an existing demo thing with new data.
+    /// </summary>
+    /// <param name="id">The unique identifier of the demo thing to update</param>
+    /// <param name="input">The new data for the demo thing</param>
+    /// <returns>A result containing the command execution result or an error</returns>
     Task<Result<CommandResult>> UpdateDemoThing(string id, UpdateDemoThingDto input);
+    
+    /// <summary>
+    /// Searches for demo things based on specified criteria.
+    /// </summary>
+    /// <param name="input">The search criteria and pagination parameters</param>
+    /// <returns>A result containing the search results with pagination information</returns>
     Task<Result<SearchOutputDto<GetDemoThingDto>>> SearchDemoThings(SearchDemoThingsInputDto input);
 }

src/1-Libraries/Application/Startup.cs

@@ -4,8 +4,19 @@
 
 namespace CanBeYours.Application;
 
+/// <summary>
+/// Startup configuration class for the Application module.
+/// This class demonstrates how to configure dependency injection for application services.
+/// The DemoThing functionality shown here is just an example to help you learn how to implement
+/// your own unique features into the current codebase.
+/// </summary>
 public static class Startup
 {
+    /// <summary>
+    /// Registers all application services and handlers with the dependency injection container.
+    /// This method is called during application startup to configure the Application module.
+    /// </summary>
+    /// <param name="services">The service collection to register services with</param>
     public static void AddApplicationModule(this IServiceCollection services)
     {
         services.RegisterHandlers(typeof(Startup));

src/1-Libraries/Application/UseCases/DemoThings/CreateDemoThing/CreateDemoThingRequest.cs

@@ -6,23 +6,45 @@
 
 namespace CanBeYours.Application.UseCases.DemoThings.CreateDemoThing;
 
+/// <summary>
+/// Command request for creating a new DemoThing entity.
+/// This class demonstrates how to implement command requests with validation attributes,
+/// immutable properties, and proper resource-based localization.
+/// The DemoThing functionality shown here is just an example to help you learn how to implement
+/// your own unique features into the current codebase.
+/// </summary>
 internal class CreateDemoThingRequest : BaseCommand
 {
+    /// <summary>
+    /// Initializes a new instance of the CreateDemoThingRequest with the required data.
+    /// </summary>
+    /// <param name="name">The name of the demo thing</param>
+    /// <param name="description">The description of the demo thing</param>
+    /// <param name="type">The type/category of the demo thing</param>
     public CreateDemoThingRequest(string name, string description, DemoThingType type)
     {
         Name = name;
         Description = description;
         Type = type;
     }
 
+    /// <summary>
+    /// The name of the demo thing. This field is required and will be displayed using localized resources.
+    /// </summary>
     [Display(Name = nameof(SharedResource.DemoThing_Name), ResourceType = typeof(SharedResource))]
     [Required(ErrorMessageResourceName = nameof(CoreResource.Required), ErrorMessageResourceType = typeof(CoreResource))]
     public string Name { get; }
 
+    /// <summary>
+    /// The description of the demo thing. This field is required and will be displayed using localized resources.
+    /// </summary>
     [Display(Name = nameof(SharedResource.DemoThing_Description), ResourceType = typeof(SharedResource))]
     [Required(ErrorMessageResourceName = nameof(CoreResource.Required), ErrorMessageResourceType = typeof(CoreResource))]
     public string Description { get; }
 
+    /// <summary>
+    /// The type of the demo thing. This field is required and determines the category of the demo thing.
+    /// </summary>
     [Display(Name = nameof(SharedResource.DemoThing_Type), ResourceType = typeof(SharedResource))]
     [Required(ErrorMessageResourceName = nameof(CoreResource.Required), ErrorMessageResourceType = typeof(CoreResource))]
     public DemoThingType Type { get; }