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
@@ -7,7 +7,7 @@ using ZB.MOM.WW.OtOpcUa.Core.Authorization;
namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.Security;
/// <summary>
/// Turns an inbound OPC UA request into a node-scoped ACL decision (#520, stage 5). The one place
/// Turns an inbound OPC UA request into a node-scoped ACL decision. The one place
/// the address space's <see cref="NodeId"/> meets <see cref="IPermissionEvaluator"/>.
/// </summary>
/// <remarks>
@@ -118,7 +118,7 @@ public sealed class DataPlaneAuthorizer
public TimeProvider Clock => _time;
/// <summary>
/// Memoized grant walks for the request-rate seams (#520 stage 6). See
/// Memoized grant walks for the request-rate seams. See
/// <see cref="SessionAclDecisionCache"/> for what it is and is not allowed to cache.
/// </summary>
public SessionAclDecisionCache Decisions { get; } = new();
@@ -204,7 +204,7 @@ public sealed class DataPlaneAuthorizer
/// <summary>
/// Whether the API key behind <paramref name="identity"/> is still usable — consulted by the two
/// server-wide role gates (<c>WriteOperate</c>, <c>AlarmAck</c>) <b>regardless of
/// <see cref="Enabled"/></b> (Gitea #563).
/// <see cref="Enabled"/></b>.
/// </summary>
/// <remarks>
/// <para>
@@ -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
@@ -27,7 +27,7 @@ public sealed class RoleCarryingUserIdentity : UserIdentity
/// <summary>
/// Initializes a new instance carrying the ACL principal and the authenticating key id alongside
/// the roles (#520 stage 5).
/// the roles.
/// </summary>
/// <param name="token">The user identity token the SDK handed to the impersonation handler.</param>
/// <param name="roles">The roles resolved by the authenticator.</param>
@@ -6,7 +6,7 @@ namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.Security;
/// <summary>
/// Memoizes the <b>grant-walk</b> half of an ACL decision per <c>(session, node, operation)</c> for one
/// authorization generation (#520 stage 6).
/// authorization generation.
/// </summary>
/// <remarks>
/// <para>