docs: fill missing XML docs and strip tracking IDs from src comments

Clears CommentChecker findings in src/ (3,280 -> 209, the remainder being false
positives like PLC-5/IEEE-754/M0.0) by adding missing summaries/params/returns,
normalising inheritdoc usage, and removing Gitea/review tracking IDs while keeping
the rationale they annotated. Comment-only: comment-stripped sources are identical
to the parent commit.
This commit is contained in:
Joseph Doherty
2026-10-15 06:14:58 -04:00
parent ebcbd81fca
commit 826312befe
430 changed files with 4434 additions and 3923 deletions
@@ -89,7 +89,7 @@ public sealed class ContinuousHistorizationOptions
/// dominant term in how fast the outbox can drain. The window bounds how many of those
/// round-trips are outstanding at once, so a large tag count cannot flood the gateway. Nothing
/// about the ack changes: the pass is still acked all-or-nothing after every group has
/// reported, and the Gitea #538 per-tag quarantine still keys on "another group wrote this
/// reported, and the per-tag quarantine still keys on "another group wrote this
/// pass".
/// </para>
/// </summary>
@@ -99,7 +99,7 @@ public sealed class ContinuousHistorizationOptions
/// Maximum un-acked outbox entries before the drop-oldest capacity policy kicks in; <c>0</c>
/// means unbounded.
/// <para>
/// Defaults to 500,000 (Gitea #538) — roughly 50 MB of FasterLog, and hours-to-days of
/// Defaults to 500,000 — roughly 50 MB of FasterLog, and hours-to-days of
/// backlog depending on tag count and update rate. It is a disk backstop for the one case
/// the per-tag quarantine cannot resolve: a historian that is unreachable or refusing
/// <em>every</em> write, where nothing proves any particular tag is at fault, so the
@@ -110,7 +110,7 @@ public sealed class ContinuousHistorizationOptions
public int Capacity { get; init; } = 500_000;
/// <summary>
/// Gitea #538: consecutive failed drain passes a single historian tag may accumulate — counted
/// consecutive failed drain passes a single historian tag may accumulate — counted
/// only across passes where <em>other</em> tags wrote successfully, so a backend outage never
/// advances it — before that tag's queued entries are discarded and the FIFO head is allowed to
/// advance. Defaults to 5; clamped to at least 1 by the recorder.
@@ -130,8 +130,8 @@ public sealed class ContinuousHistorizationOptions
public double MaxBackoffSeconds { get; init; } = 30;
/// <summary>
/// Gitea #672: when <c>true</c> (the default), a redundant node whose capture is stood down for its
/// mesh-partner Primary (Gitea #537) resumes capturing as soon as the cluster failure detector reports
/// when <c>true</c> (the default), a redundant node whose capture is stood down for its
/// mesh-partner Primary resumes capturing as soon as the cluster failure detector reports
/// that Primary <b>unreachable</b>, instead of waiting for auto-down and a fresh redundancy snapshot.
/// <para>
/// A crashed Primary otherwise leaves a capture hole of failure-detection + auto-down (~25 s on the
@@ -141,7 +141,7 @@ public sealed class ContinuousHistorizationOptions
/// detection onward, and a briefly-unreachable-but-alive Primary overlaps the standby. SqlServer and
/// QuestDB absorb a duplicate of a source-timestamped sample idempotently; a driver with no source
/// timestamp (e.g. Modbus, stamped with each node's own poll time) writes a duplicate row on every
/// backend, and the Gateway backend stores duplicates. <c>false</c> restores the pre-#672 behaviour.
/// backend, and the Gateway backend stores duplicates. <c>false</c> restores the previous behaviour.
/// Only the historization capture verdict is affected — never the alarm drain or the Primary data-plane
/// gate.
/// </para>