docs: more code comments and minor style refactoring

api/Health/ApiHealthCheck.cs

@@ -3,6 +3,9 @@ using Microsoft.Extensions.Diagnostics.HealthChecks;
 
 namespace BonchCalendar.Health;
 
+/// <summary>
+/// Healthcheck service for sut.ru API.
+/// </summary>
 public class ApiHealthCheck(IssueTrackingService trackingService) : IHealthCheck
 {
 	public async Task<HealthCheckResult> CheckHealthAsync(
@@ -11,8 +14,12 @@ public class ApiHealthCheck(IssueTrackingService trackingService) : IHealthCheck
 	{
 		Dictionary<string, object> report = trackingService.GetReport();
 
+		// We deem service "unhealthy" if any of the last requests to the API were unsuccessful.
 		if (report.Count > 0)
-			return HealthCheckResult.Unhealthy(description: "We're having issues with fetching data from the timetable website.", data: report);
+			return HealthCheckResult.Unhealthy(
+				description: "We're having issues with fetching data from the timetable website.",
+				data: report
+			);
 
 		return HealthCheckResult.Healthy();
 	}

api/Health/HealthCheckWriter.cs

@@ -7,18 +7,18 @@ namespace BonchCalendar.Health;
 public static class HealthCheckWriter
 {
 	private static readonly byte[] _emptyResponse = [ (byte)'{', (byte)'}' ];
-	private static JsonSerializerContext? _jsonContext = null;
-
-	public static JsonSerializerContext JsonContext => _jsonContext ??= CreateSerializerContext();
+	private static readonly JsonSerializerContext _jsonContext = CreateSerializerContext();
 
 	public static async Task WriteHealthCheckResponse(HttpContext context, HealthReport report)
 	{
 		if (report is null)
 		{
+			// Just in case, but this should not ever happen.
 			await context.Response.BodyWriter.WriteAsync(_emptyResponse).ConfigureAwait(false);
 			return;
 		}
 
+		// Create DTO from the report.
 		HealthResponse response = new(
 			Status: report.Status,
 			TotalDuration: report.TotalDuration,
@@ -33,9 +33,9 @@ public static class HealthCheckWriter
 			)
 		);
 
+		// Write DTO to the response body.
 		context.Response.ContentType = "application/json; charset=utf-8";
-
-		await JsonSerializer.SerializeAsync(context.Response.Body, response, typeof(HealthResponse), JsonContext).ConfigureAwait(false);
+		await JsonSerializer.SerializeAsync(context.Response.Body, response, typeof(HealthResponse), _jsonContext).ConfigureAwait(false);
 	}
 
 	private static AppJsonSerializerContext CreateSerializerContext()
@@ -53,12 +53,25 @@ public static class HealthCheckWriter
 	}
 }
 
+/// <summary>
+/// Response body for /health endpoint.
+/// </summary>
+/// <param name="Status">Overall status of the application.</param>
+/// <param name="TotalDuration">Total time it took to complete the health check.</param>
+/// <param name="Entries">List of subcomponent healthcheck reports.</param>
 public record HealthResponse(
 	HealthStatus Status,
 	TimeSpan TotalDuration,
 	IReadOnlyDictionary<string, HealthResponseEntry> Entries
 );
 
+/// <summary>
+/// Healthcheck report for a subcomponent.
+/// </summary>
+/// <param name="Status">Status of the subcomponent.</param>
+/// <param name="Description">Report remarks.</param>
+/// <param name="Duration">Time it took to complete health check for this subcomponent.</param>
+/// <param name="Data">Addtional report data.</param>
 public record HealthResponseEntry(
 	HealthStatus Status,
 	string? Description,