From 5a14da619f2b25ae01b243e52c230cbb2c75e8f0 Mon Sep 17 00:00:00 2001 From: Alex Fischer <183024988+SuperGamer001@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:30:11 -0800 Subject: [PATCH] Added Documentation to controllers and models --- GameBox/Controllers/GameModelsController.cs | 73 ++++++++++++++++++--- GameBox/Controllers/HomeController.cs | 17 +++++ GameBox/Models/ApplicationUser.cs | 7 ++ GameBox/Models/ErrorViewModel.cs | 10 +++ GameBox/Models/GameModel.cs | 49 +++++++++++++- 5 files changed, 144 insertions(+), 12 deletions(-) diff --git a/GameBox/Controllers/GameModelsController.cs b/GameBox/Controllers/GameModelsController.cs index 94d94fc..3622ed9 100644 --- a/GameBox/Controllers/GameModelsController.cs +++ b/GameBox/Controllers/GameModelsController.cs @@ -12,24 +12,42 @@ namespace GameBox.Controllers { + /// + /// MVC controller responsible for CRUD operations on entities. + /// Contains actions for listing, viewing details, creating, editing and deleting games. + /// public class GameModelsController : Controller { private readonly ApplicationDbContext _context; private readonly UserManager _userManager; + /// + /// Initializes a new instance of the class. + /// + /// The application's database context. + /// User manager used to obtain information about the current user. public GameModelsController(ApplicationDbContext context, UserManager userManager) { _context = context; _userManager = userManager; } - // GET: GameModels + /// + /// GET: GameModels + /// Returns a view with all game models. + /// + /// A task that resolves to an rendering the index view. public async Task Index() { return View(await _context.GameModels.ToListAsync()); } - // GET: GameModels/Details/5 + /// + /// GET: GameModels/Details/{id} + /// Shows details for a single game model. + /// + /// The id of the game to display details for. + /// NotFound if id is null or the game does not exist; otherwise the details view. public async Task Details(int? id) { if (id == null) @@ -47,15 +65,25 @@ public async Task Details(int? id) return View(gameModel); } - // GET: GameModels/Create + /// + /// GET: GameModels/Create + /// Returns the form to create a new game. Requires authentication. + /// + /// The create view. [Authorize] public IActionResult Create() { return View(); } - // POST: GameModels/Create - // To protect from overposting attacks, enable the specific properties you want to bind to. + /// + /// POST: GameModels/Create + /// Creates a new game and assigns the currently authenticated user as the owner. + /// Prevents overposting by binding only allowed properties. + /// Requires a valid antiforgery token and authentication. + /// + /// The incoming model bound from the form. + /// Redirects to Index on success; otherwise returns the create view with validation errors. [HttpPost] [ValidateAntiForgeryToken] [Authorize] @@ -85,7 +113,12 @@ public async Task Create([Bind("Id,Name,Description")] GameModel return View(gameModel); } - // GET: GameModels/Edit/5 + /// + /// GET: GameModels/Edit/{id} + /// Returns the edit form for the specified game. + /// + /// The id of the game to edit. + /// NotFound if id is null or the game does not exist; otherwise the edit view. public async Task Edit(int? id) { if (id == null) @@ -101,8 +134,13 @@ public async Task Edit(int? id) return View(gameModel); } - // POST: GameModels/Edit/5 - // To protect from overposting attacks, enable the specific properties you want to bind to. + /// + /// POST: GameModels/Edit/{id} + /// Updates an existing game. Protects against overposting by binding allowed properties only. + /// + /// The id of the game being edited. + /// The model values submitted from the form. + /// Redirects to Index on success; otherwise returns the edit view with validation errors. [HttpPost] [ValidateAntiForgeryToken] public async Task Edit(int id, [Bind("Id,Name,Description,Rating")] GameModel gameModel) @@ -135,7 +173,12 @@ public async Task Edit(int id, [Bind("Id,Name,Description,Rating" return View(gameModel); } - // GET: GameModels/Delete/5 + /// + /// GET: GameModels/Delete/{id} + /// Shows a confirmation view to delete the specified game. + /// + /// The id of the game to delete. + /// NotFound if id is null or the game does not exist; otherwise the delete confirmation view. public async Task Delete(int? id) { if (id == null) @@ -153,7 +196,12 @@ public async Task Delete(int? id) return View(gameModel); } - // POST: GameModels/Delete/5 + /// + /// POST: GameModels/Delete/{id} + /// Deletes the specified game after confirmation. + /// + /// The id of the game to delete. + /// Redirects to the index view after deletion. [HttpPost, ActionName("Delete")] [ValidateAntiForgeryToken] public async Task DeleteConfirmed(int id) @@ -168,6 +216,11 @@ public async Task DeleteConfirmed(int id) return RedirectToAction(nameof(Index)); } + /// + /// Checks whether a game exists in the database. + /// + /// The id of the game to check. + /// True if the game exists; otherwise false. private bool GameModelExists(int id) { return _context.GameModels.Any(e => e.Id == id); diff --git a/GameBox/Controllers/HomeController.cs b/GameBox/Controllers/HomeController.cs index 396b48b..fa904dd 100644 --- a/GameBox/Controllers/HomeController.cs +++ b/GameBox/Controllers/HomeController.cs @@ -4,18 +4,35 @@ namespace GameBox.Controllers { + /// + /// Controller responsible for rendering the application's home pages such as the index, + /// privacy page, and the global error page. + /// public class HomeController : Controller { + /// + /// Renders the application home page (index). + /// + /// An that renders the Index view. public IActionResult Index() { return View(); } + /// + /// Renders the privacy information page. + /// + /// An that renders the Privacy view. public IActionResult Privacy() { return View(); } + /// + /// Displays the error view with request tracing information. + /// The response is not cached to ensure fresh error details are shown. + /// + /// An that renders the Error view with an . [ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)] public IActionResult Error() { diff --git a/GameBox/Models/ApplicationUser.cs b/GameBox/Models/ApplicationUser.cs index 239f854..cc4482c 100644 --- a/GameBox/Models/ApplicationUser.cs +++ b/GameBox/Models/ApplicationUser.cs @@ -3,8 +3,15 @@ namespace GameBox.Models { + /// + /// Represents an application user with extended profile and social features. + /// Extends the base IdentityUser with additional GameBox-specific properties. + /// public class ApplicationUser : IdentityUser { + /// + /// Gets or sets the collection of users who follow this user. + /// public ICollection Followers { get; set; } = new List(); } } diff --git a/GameBox/Models/ErrorViewModel.cs b/GameBox/Models/ErrorViewModel.cs index 148c699..23b4fff 100644 --- a/GameBox/Models/ErrorViewModel.cs +++ b/GameBox/Models/ErrorViewModel.cs @@ -1,9 +1,19 @@ namespace GameBox.Models { + /// + /// View model for displaying error information to users. + /// public class ErrorViewModel { + /// + /// Gets or sets the unique request ID associated with the error. + /// public string? RequestId { get; set; } + /// + /// Gets a value indicating whether the request ID should be displayed to the user. + /// Returns true if RequestId is not null or empty. + /// public bool ShowRequestId => !string.IsNullOrEmpty(RequestId); } } diff --git a/GameBox/Models/GameModel.cs b/GameBox/Models/GameModel.cs index 8818aa4..ce21f2f 100644 --- a/GameBox/Models/GameModel.cs +++ b/GameBox/Models/GameModel.cs @@ -5,38 +5,83 @@ namespace GameBox.Models { - + /// + /// Represents a game in the GameBox application. + /// public class GameModel { + /// + /// Gets or sets the unique identifier for the game. + /// [Key] [DatabaseGenerated(DatabaseGeneratedOption.Identity)] public int Id { get; set; } + /// + /// Gets or sets the name of the game. + /// [StringLength(100, MinimumLength = 1, ErrorMessage = "Game name cannot exceed 100 characters.")] public required string Name { get; set; } + /// + /// Gets or sets the description of the game. + /// [StringLength(1000, ErrorMessage = "Description cannot exceed 1000 characters.")] public required string Description { get; set; } = string.Empty; + /// + /// Gets or sets the rating for the game on a scale of 1 to 10. + /// [Range(1, 10, ErrorMessage = "Ratings must be between 1 and 10")] public int? Rating { get; set; } + /// + /// Gets or sets the ID of the user who owns this game. + /// // Shouldn't this work either way? [ForeignKey("ApplicationUser")] public string? OwnerId { get; set; } + /// + /// Gets or sets the navigation property to the application user who owns this game. + /// [ForeignKey(nameof(OwnerId))] public ApplicationUser? Owner { get; set; } } } +/// +/// View model for displaying a paginated list of games with search capabilities. +/// public class GameListViewModel { + /// + /// Gets or sets the collection of games to display. + /// public required IEnumerable Games { get; set; } + + /// + /// Gets or sets the current page number in the pagination. + /// public int CurrentPage { get; set; } + + /// + /// Gets or sets the total number of pages available. + /// public int TotalPages { get; set; } + + /// + /// Gets or sets the number of items to display per page. + /// public int PageSize { get; set; } + + /// + /// Gets or sets the total number of items across all pages. + /// public int TotalItems { get; set; } + + /// + /// Gets or sets the search term used to filter the games list. + /// public string? SearchTerm { get; set; } - } \ No newline at end of file