docs: more code comments and minor style refactoring

api/Services/TimetableService.cs

@@ -4,6 +4,9 @@ using Ical.Net.Serialization;
 
 namespace BonchCalendar.Services;
 
+/// <summary>
+/// Service for retrieving timetable.
+/// </summary>
 public class TimetableService(
 	ApiService apiService,
 	ParsingService parsingService,
@@ -11,7 +14,12 @@ public class TimetableService(
 	IHostEnvironment environment
 )
 {
-	public async Task<string?> TryServingFromCacheAsync(int groupId)
+	/// <summary>
+	/// Try to retrieve timetable from application's cache.
+	/// </summary>
+	/// <param name="groupId">ID of a group to retrieve timetable for.</param>
+	/// <returns><c>null</c> if cache for this timetable is not present, or is older than 6 hours. Otherwise, timetable content in iCal format.</returns>
+	public async Task<string?> TryGetTimetableFromCacheAsync(int groupId)
 	{
 		string cacheFile = GetCachePath(groupId);
 
@@ -24,17 +32,28 @@ public class TimetableService(
 			return null;
 		}
 
+		logger.LogInformation("Calendar for group {GroupId} is present in cache ({CacheFile}).", groupId, cacheFile);
+
 		return await File.ReadAllTextAsync(cacheFile);
 	}
 
+	/// <summary>
+	/// Retrieve timetable for specified group from sut.ru API.
+	/// </summary>
+	/// <param name="saveToCache">If set to <c>true</c>, result timetable will be wirtten to cache for that group.</param>
+	/// <param name="transform">Action delegate that can be used to manipulate the result <see cref="Calendar"/> object, before converting it to iCal.</param>
+	/// <returns>A string that contains timetable in iCal format.</returns>
 	public async Task<string> GetTimetableAsync(int facultyId, int groupId, bool saveToCache = true, Action<Calendar>? transform = null)
 	{
+		// We need semester start date, since the regular timetable is represented on sut.ru semester week numbers.
 		DateTime semesterStartDate = await apiService.GetSemesterStartDateAsync(groupId);
 		string groupName = (await apiService.GetGroupsListAsync(facultyId, 0))[groupId];
 
+		// Retrieve and parse regular timetable first, since it's the only timetable that has different structure.
 		string classesRaw = await apiService.GetScheduleDocumentAsync(groupId, TimetableType.Classes);
 		List<CalendarEvent> timetable = [.. parsingService.ParseGeneralTimetable(classesRaw, semesterStartDate, groupName)];
 
+		// Retrieve and parse other timetables using a loop, since they all can be parsed using the same parser.
 		TimetableType[] types = [TimetableType.Attestations, TimetableType.Exams, TimetableType.ExamsForExtramural];
 		foreach (TimetableType type in types)
 		{
@@ -42,13 +61,17 @@ public class TimetableService(
 			timetable.AddRange(parsingService.ParseExamTimetable(classesRaw, groupName));
 		}
 
+		// Create and configure the calendar.
 		Calendar calendar = new();
 		calendar.AddTimeZone(new VTimeZone("Europe/Moscow"));
 		calendar.Properties.Add(new CalendarProperty("X-WR-CALNAME", groupName));
 		calendar.Properties.Add(new CalendarProperty("X-WR-TIMEZONE", "Europe/Moscow"));
-		calendar.Properties.Add(new CalendarProperty("REFRESH-INTERVAL;VALUE=DURATION", "PT6H"));
+		calendar.Properties.Add(new CalendarProperty("REFRESH-INTERVAL;VALUE=DURATION", "PT6H"));	// Specifies how often calendar client should poll for new timetable.
 		calendar.Events.AddRange(timetable);
-		transform?.Invoke(calendar);
+
+		transform?.Invoke(calendar);		// If transform delegate is not null, invoke it.
+
+		// Serialize calendar to iCal format.
 		string content = new CalendarSerializer().SerializeToString(calendar)!;
 
 		if (saveToCache)