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
@@ -26,7 +26,7 @@ public interface IOpcUaUserAuthenticator
Task<OpcUaUserAuthResult> AuthenticateUserNameAsync(string username, string password, CancellationToken ct);
/// <summary>
/// Resolves what an <b>anonymous</b> session is allowed to do (#520). Anonymous is a normal
/// Resolves what an <b>anonymous</b> session is allowed to do. Anonymous is a normal
/// principal — <see cref="OpcUaPrincipals.Anonymous"/> — not a special case, so it can be granted
/// read or write through ordinary ACL rows.
/// </summary>
@@ -38,7 +38,7 @@ public interface IOpcUaUserAuthenticator
/// </para>
/// <para>
/// The default implementation admits anonymous with <b>no roles</b>, which is exactly the
/// behaviour before #520: an anonymous session connects, and every role-gated operation
/// behaviour before per-key ACLs: an anonymous session connects, and every role-gated operation
/// (write, alarm ack) denies. Implementors that can resolve grants override it; the rest
/// keep the safe status quo rather than being forced to reimplement it.
/// </para>
@@ -53,8 +53,8 @@ public interface IOpcUaUserAuthenticator
/// <summary>Outcome of a UserName authentication attempt. <see cref="Roles"/> populates the session identity's role set.</summary>
/// <remarks>
/// <para>
/// ⚠️ <b><see cref="DisplayName"/> is not the principal, and assuming it was is a live trap</b>
/// (#520 stage 5). The authenticator passes the principal as the display name, but
/// ⚠️ <b><see cref="DisplayName"/> is not the principal, and assuming it was is a live trap</b>.
/// The authenticator passes the principal as the display name, but
/// <c>RoleCarryingUserIdentity</c> derives <c>UserIdentity.DisplayName</c> from the presented
/// <b>token</b> — which for a key-bearing client is the static username <c>apikey</c>, the same
/// for every key in the fleet. So the principal was being dropped on the floor at the identity