Convert PocketBase dates to Berlin time; document code conventions

Elternbeirat.Contracts/Event.cs

@@ -2,38 +2,68 @@ using System.Text.Json.Serialization;
 
 namespace Elternbeirat.Contracts;
 
-/// <summary>A calendar entry. Sorted by <see cref="Start"/>.</summary>
+/// <summary>
+///     A calendar entry of the Elternbeirat, as stored in PocketBase.
+/// </summary>
+/// <remarks>
+///     Event lists are ordered by <see cref="Start"/>. Unset optional text fields are
+///     <see cref="string.Empty"/>, never <see langword="null"/>.
+/// </remarks>
 public record Event
 {
-    /// <summary>PocketBase record id.</summary>
+    /// <summary>
+    ///     Gets the PocketBase record id.
+    /// </summary>
     [JsonPropertyName("id")]
     public string Id { get; init; } = "";
 
     /// <summary>
-    /// Start of the event with date and time. Stored as UTC by PocketBase but
-    /// read as local time (Europe/Berlin) by convention. An all-day event uses
-    /// 00:00 as the time.
+    ///     Gets the start of the event as Europe/Berlin wall-clock time.
     /// </summary>
+    /// <remarks>
+    ///     PocketBase stores the value in UTC; it is converted to Berlin local time on
+    ///     deserialization, with daylight saving applied. An all-day event uses 00:00
+    ///     as the time.
+    /// </remarks>
     [JsonPropertyName("start")]
     public DateTime Start { get; init; }
 
-    /// <summary>Optional end of the event; null when unset.</summary>
+    /// <summary>
+    ///     Gets the optional end of the event as Europe/Berlin wall-clock time.
+    /// </summary>
+    /// <value>
+    ///     The end time, or <see langword="null"/> if the event has no end.
+    /// </value>
     [JsonPropertyName("end")]
     public DateTime? End { get; init; }
 
-    /// <summary>Event name, e.g. "Elternbeiratssitzung".</summary>
+    /// <summary>
+    ///     Gets the event name, e.g. <c>"Elternbeiratssitzung"</c>.
+    /// </summary>
     [JsonPropertyName("title")]
     public string Title { get; init; } = "";
 
-    /// <summary>Optional location, e.g. "Aula".</summary>
+    /// <summary>
+    ///     Gets the optional location, e.g. <c>"Aula"</c>.
+    /// </summary>
+    /// <value>
+    ///     The location, or <see cref="string.Empty"/> if none is set.
+    /// </value>
     [JsonPropertyName("location")]
     public string Location { get; init; } = "";
 
-    /// <summary>Optional note, e.g. "Anmeldung erforderlich".</summary>
+    /// <summary>
+    ///     Gets the optional note, e.g. <c>"Anmeldung erforderlich"</c>.
+    /// </summary>
+    /// <value>
+    ///     The note, or <see cref="string.Empty"/> if none is set.
+    /// </value>
     [JsonPropertyName("note")]
     public string Note { get; init; } = "";
 
-    /// <summary>Whether the event is visible to visitors.</summary>
+    /// <summary>
+    ///     Gets a value indicating whether the event is visible to visitors of the site.
+    /// </summary>
     [JsonPropertyName("public")]
     public bool Public { get; init; }
 }