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
@@ -31,7 +31,7 @@ public sealed record ManualFailoverSnapshot(string? PrimaryAddress, IReadOnlyLis
/// moves with it and OPC UA clients re-select.
/// </para>
/// <para>
/// Post-Phase-6 (per-cluster mesh split): the Primary is elected per application
/// With the per-cluster mesh split: the Primary is elected per application
/// <c>Cluster</c>, because each cluster's redundant pair now runs its own independent
/// 2-node Akka mesh. This service therefore acts on <b>this pair's own</b> Primary.
/// </para>
@@ -39,6 +39,7 @@ public sealed record ManualFailoverSnapshot(string? PrimaryAddress, IReadOnlyLis
public interface IManualFailoverService
{
/// <summary>Reads the current driver membership from live cluster state.</summary>
/// <returns>A snapshot of the current driver membership.</returns>
ManualFailoverSnapshot GetSnapshot();
/// <summary>
@@ -123,7 +123,7 @@ public sealed class ManualFailoverService : IManualFailoverService
}
private static List<Member> OrderedDrivers(IEnumerable<Member> members) => members
// R3-04 (01/C-9): GossipedRolesHave, not ordinal Contains — a peer gossiping a miscased
// GossipedRolesHave, not ordinal Contains — a peer gossiping a miscased
// 'Driver' (rolling-upgrade window) must still be a manual-failover candidate.
.Where(m => m.Status == MemberStatus.Up && RoleParser.GossipedRolesHave(m.Roles, RedundancyStateActor.DriverRole))
.OrderBy(m => m, Member.AgeOrdering)
@@ -190,13 +190,12 @@ public sealed class RedundancyStateActor : ReceiveActor, IWithTimers
if (string.IsNullOrWhiteSpace(host)) continue;
var isPrimary = driverPrimary is not null && driverPrimary == member.Address;
// R3-04 (01/C-9): GossipedRolesHave, not ordinal Contains — a peer running an older build
// GossipedRolesHave, not ordinal Contains — a peer running an older build
// can still gossip a miscased 'Driver' during a rolling upgrade, and this list is what
// /hosts and /fleet render, so a miscased-but-genuinely-driver member must not read as
// Detached. NOTE: this does NOT reach SelectDriverPrimary/driverPrimary above — that
// delegates to ClusterActiveNode.OldestUpMember (ZB.MOM.WW.Health.Akka), which matches via
// Akka's own ordinal Member.HasRole and is not this repo's to change (see R3-04 execution
// notes). So a member gossiping only 'Driver' now classifies Secondary rather than
// Akka's own ordinal Member.HasRole and is not this repo's to change. So a member gossiping only 'Driver' now classifies Secondary rather than
// Detached, but a PAIR that BOTH gossip 'Driver' still elects no Primary.
var role = RoleParser.GossipedRolesHave(member.Roles, DriverRole)
? (isPrimary ? CommonsRedundancyRole.Primary : CommonsRedundancyRole.Secondary)