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; }
 }

Elternbeirat.Contracts/Faq.cs

@@ -3,27 +3,40 @@ using System.Text.Json.Serialization;
 namespace Elternbeirat.Contracts;
 
 /// <summary>
-/// A single question and answer, grouped on the FAQ page by <see cref="Topic"/>.
+///     A single question and answer of the FAQ, as stored in PocketBase.
 /// </summary>
+/// <remarks>
+///     On the FAQ page, entries are grouped by <see cref="Topic"/>.
+/// </remarks>
 public record Faq
 {
-    /// <summary>PocketBase record id.</summary>
+    /// <summary>
+    ///     Gets the PocketBase record id.
+    /// </summary>
     [JsonPropertyName("id")]
     public string Id { get; init; } = "";
 
-    /// <summary>The question as a parent would phrase it.</summary>
+    /// <summary>
+    ///     Gets the question as a parent would phrase it.
+    /// </summary>
     [JsonPropertyName("question")]
     public string Question { get; init; } = "";
 
-    /// <summary>The answer in Markdown.</summary>
+    /// <summary>
+    ///     Gets the answer as Markdown.
+    /// </summary>
     [JsonPropertyName("answer")]
     public string Answer { get; init; } = "";
 
-    /// <summary>Topic the question is grouped under, e.g. "mensa".</summary>
+    /// <summary>
+    ///     Gets the topic the question is grouped under, e.g. <c>"mensa"</c>.
+    /// </summary>
     [JsonPropertyName("topic")]
     public string Topic { get; init; } = "";
 
-    /// <summary>Whether the question is visible to visitors.</summary>
+    /// <summary>
+    ///     Gets a value indicating whether the question is visible to visitors of the site.
+    /// </summary>
     [JsonPropertyName("public")]
     public bool Public { get; init; }
 }

Elternbeirat.Contracts/Page.cs

@@ -3,45 +3,77 @@ using System.Text.Json.Serialization;
 namespace Elternbeirat.Contracts;
 
 /// <summary>
-/// A content page. Pages also drive the site navigation: <see cref="Location"/>
-/// and <see cref="Order"/> decide where and in which order a page appears in the
-/// header or footer menu, and <see cref="Embed"/> lists dynamic blocks (posts,
-/// events, faqs) rendered below the page body.
+///     A content page of the site, as stored in PocketBase.
 /// </summary>
+/// <remarks>
+///     Pages also drive the site navigation: <see cref="Location"/> and
+///     <see cref="Order"/> decide where and in which order a page appears in the
+///     header or footer menu. <see cref="Embed"/> lists dynamic blocks rendered
+///     below the page body.
+/// </remarks>
 public record Page
 {
-    /// <summary>PocketBase record id.</summary>
+    /// <summary>
+    ///     Gets the PocketBase record id.
+    /// </summary>
     [JsonPropertyName("id")]
     public string Id { get; init; } = "";
 
-    /// <summary>Heading shown to visitors; may contain umlauts and spaces.</summary>
+    /// <summary>
+    ///     Gets the heading shown to visitors.
+    /// </summary>
+    /// <remarks>
+    ///     Free text; may contain umlauts and spaces. For the URL, see <see cref="Slug"/>.
+    /// </remarks>
     [JsonPropertyName("title")]
     public string Title { get; init; } = "";
 
-    /// <summary>Page body in Markdown.</summary>
+    /// <summary>
+    ///     Gets the page body as Markdown.
+    /// </summary>
     [JsonPropertyName("body")]
     public string Body { get; init; } = "";
 
-    /// <summary>Where the page appears in the navigation: "header" or "footer".</summary>
+    /// <summary>
+    ///     Gets the navigation menu the page appears in.
+    /// </summary>
+    /// <value>
+    ///     Either <c>"header"</c> or <c>"footer"</c>.
+    /// </value>
     [JsonPropertyName("location")]
     public string Location { get; init; } = "";
 
-    /// <summary>Sort order within its navigation location; smaller is earlier.</summary>
+    /// <summary>
+    ///     Gets the sort order within the navigation menu given by <see cref="Location"/>.
+    /// </summary>
+    /// <value>
+    ///     The sort key; pages with smaller values appear first.
+    /// </value>
     [JsonPropertyName("order")]
     public double Order { get; init; }
 
-    /// <summary>URL slug (lowercase, no umlauts), e.g. "board" -> /board.</summary>
+    /// <summary>
+    ///     Gets the URL slug of the page, e.g. <c>"board"</c> for <c>/board</c>.
+    /// </summary>
+    /// <value>
+    ///     A lowercase path segment without umlauts.
+    /// </value>
     [JsonPropertyName("slug")]
     public string Slug { get; init; } = "";
 
     /// <summary>
-    /// Dynamic blocks to render below the body: any of "posts", "events", "faqs".
-    /// Empty for a plain text page.
+    ///     Gets the dynamic blocks rendered below the <see cref="Body"/>.
     /// </summary>
+    /// <value>
+    ///     Any of <c>"posts"</c>, <c>"events"</c> and <c>"faqs"</c>, or an empty list
+    ///     for a plain text page.
+    /// </value>
     [JsonPropertyName("embed")]
     public IReadOnlyList<string> Embed { get; init; } = [];
 
-    /// <summary>Whether the page is visible to visitors.</summary>
+    /// <summary>
+    ///     Gets a value indicating whether the page is visible to visitors of the site.
+    /// </summary>
     [JsonPropertyName("public")]
     public bool Public { get; init; }
 }

Elternbeirat.Contracts/Post.cs

@@ -2,33 +2,57 @@ using System.Text.Json.Serialization;
 
 namespace Elternbeirat.Contracts;
 
-/// <summary>A news post. Sorted by <see cref="Date"/>, newest first.</summary>
+/// <summary>
+///     A news post of the site, as stored in PocketBase.
+/// </summary>
+/// <remarks>
+///     Post lists are ordered by <see cref="Date"/>, newest first.
+/// </remarks>
 public record Post
 {
-    /// <summary>PocketBase record id.</summary>
+    /// <summary>
+    ///     Gets the PocketBase record id.
+    /// </summary>
     [JsonPropertyName("id")]
     public string Id { get; init; } = "";
 
     /// <summary>
-    /// Publication date. Stored as UTC by PocketBase but read as local time
-    /// (Europe/Berlin) by convention; only the date part is shown.
+    ///     Gets the publication date 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. Only the date part is shown.
+    /// </remarks>
     [JsonPropertyName("date")]
     public DateTime Date { get; init; }
 
-    /// <summary>Post heading shown to visitors; may contain umlauts and spaces.</summary>
+    /// <summary>
+    ///     Gets the heading shown to visitors.
+    /// </summary>
+    /// <remarks>
+    ///     Free text; may contain umlauts and spaces. For the URL, see <see cref="Slug"/>.
+    /// </remarks>
     [JsonPropertyName("title")]
     public string Title { get; init; } = "";
 
-    /// <summary>Post body in Markdown.</summary>
+    /// <summary>
+    ///     Gets the post body as Markdown.
+    /// </summary>
     [JsonPropertyName("body")]
     public string Body { get; init; } = "";
 
-    /// <summary>URL slug (lowercase, no umlauts), e.g. "herbstbasar" -> /posts/herbstbasar.</summary>
+    /// <summary>
+    ///     Gets the URL slug of the post, e.g. <c>"herbstbasar"</c> for <c>/posts/herbstbasar</c>.
+    /// </summary>
+    /// <value>
+    ///     A lowercase path segment without umlauts.
+    /// </value>
     [JsonPropertyName("slug")]
     public string Slug { get; init; } = "";
 
-    /// <summary>Whether the post is visible to visitors.</summary>
+    /// <summary>
+    ///     Gets a value indicating whether the post is visible to visitors of the site.
+    /// </summary>
     [JsonPropertyName("public")]
     public bool Public { get; init; }
 }