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
@@ -8,7 +8,7 @@ namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
/// <summary>
/// Node-level defaults for the AbCip driver (final review I1), bound from <c>Drivers:AbCip</c>. Lets an
/// operator pin the transport an AbCip driver with NO <c>transport</c> key runs on — at upgrade time,
/// without editing (or being able to edit, #576) every driver config. An explicit per-driver
/// without editing (or being able to edit) every driver config. An explicit per-driver
/// <c>transport</c> key still wins. Overridable by environment variable
/// <c>Drivers__AbCip__DefaultTransport</c>.
/// </summary>
@@ -66,7 +66,7 @@ public static class AbCipDriverDefaultsRegistration
/// Binds + validates <c>Drivers:AbCip</c>. Unconditional on every role: BOTH consumers need it — the driver
/// factory (driver role) and the Test Connect probe (admin role, which must probe the stack the driver would
/// run). A bad value fails host start rather than silently falling back. <c>Program.cs</c> must call this
/// (pinned by <c>AbCipDriverDefaultsOptionsTests</c>): without it an operator's pin is silently ignored (#585).
/// (pinned by <c>AbCipDriverDefaultsOptionsTests</c>): without it an operator's pin is silently ignored.
/// </summary>
/// <param name="services">The service collection.</param>
/// <param name="configuration">The host configuration.</param>
@@ -12,7 +12,7 @@ using ZB.MOM.WW.OtOpcUa.OpcUaServer.Security;
namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
/// <summary>
/// Composition of the OPC UA data-plane authentication + authorization seams (#520), extracted from
/// Composition of the OPC UA data-plane authentication + authorization seams, extracted from
/// <c>Program.cs</c> so the role-conditional branches are reachable from a test.
/// </summary>
/// <remarks>
@@ -42,7 +42,7 @@ public static class DataPlaneAuthRegistration
// matched". TryAdd so a test (or a future host) can substitute one before this runs.
services.TryAddSingleton(TimeProvider.System);
// #520 stage 5 — the node-scoped ACL gate. Registered on EVERY node, not just driver ones, because
// the node-scoped ACL gate. Registered on EVERY node, not just driver ones, because
// OtOpcUaServerHostedService takes it as a constructor parameter and the built-in container resolves
// constructors by whether every parameter is registered, not by whether the parameter type is nullable.
// That is the same trap the IOpcUaUserAuthenticator and IDataPlaneAuthoritySource registrations below
@@ -19,6 +19,8 @@ public static class HistorianBackendRegistry
public const string SqlServerBackendName = "SqlServer";
/// <summary>Binds the <c>ServerHistorian:SqlServer</c> section (shared by the registry and the validator).</summary>
/// <param name="configuration">The host configuration.</param>
/// <returns>The bound SQL Server historian options.</returns>
public static SqlServerHistorianOptions BindSqlServer(IConfiguration configuration)
{
var o = new SqlServerHistorianOptions();
@@ -30,6 +32,8 @@ public static class HistorianBackendRegistry
public const string QuestDbBackendName = "QuestDb";
/// <summary>Binds the <c>ServerHistorian:QuestDb</c> section (shared by the registry and the validator).</summary>
/// <param name="configuration">The host configuration.</param>
/// <returns>The bound QuestDB historian options.</returns>
public static QuestDbHistorianOptions BindQuestDb(IConfiguration configuration)
{
var o = new QuestDbHistorianOptions();
@@ -49,10 +53,15 @@ public static class HistorianBackendRegistry
public static IReadOnlyCollection<string> KnownBackends { get; } = Factories.Keys.ToArray();
/// <summary>True when <paramref name="backend"/> names a registered backend.</summary>
/// <param name="backend">The backend name to look up; may be null.</param>
/// <returns><see langword="true"/> when the name is registered.</returns>
public static bool IsKnown(string? backend) =>
!string.IsNullOrWhiteSpace(backend) && Factories.ContainsKey(backend.Trim());
/// <summary>Builds the provider for <c>options.Backend</c>; throws <see cref="OptionsValidationException"/> if unknown.</summary>
/// <param name="options">The server historian options naming the backend.</param>
/// <param name="configuration">The host configuration passed to the backend factory.</param>
/// <returns>The provider for the configured backend.</returns>
public static IHistorianBackendProvider Resolve(ServerHistorianOptions options, IConfiguration configuration)
{
ArgumentNullException.ThrowIfNull(options);
@@ -51,7 +51,7 @@ public sealed class LdapOptionsValidator : OptionsValidatorBase<LdapOptions>
// A non-positive connect/search timeout would leave the shared library unbounded against a hung
// directory, so fail fast. The other four S2 knobs validated here (AuthTimeoutMs,
// MaxConcurrentAuthentications, OutageFailureThreshold, OutageCooldownSeconds) went with
// LdapOpcUaUserAuthenticator in #520 — they guarded an LDAP bind running inline on OPC UA
// LdapOpcUaUserAuthenticator — they guarded an LDAP bind running inline on OPC UA
// session activation, and no remaining LDAP consumer runs on that path.
builder.RequireThat(options.ConnectionTimeoutMs > 0,
"Ldap:ConnectionTimeoutMs must be > 0.");
@@ -19,7 +19,7 @@ namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
/// <c>Program.cs</c> so the wiring is covered by a DI resolution test — <c>Program.cs</c> is
/// top-level statements and cannot be exercised directly, which is exactly how a
/// "registered but never resolvable" defect ships unnoticed. This family has shipped that
/// defect three times (Secrets 0.2.0, Secrets 0.2.2, ScadaBridge #22).
/// defect three times (Secrets 0.2.0, Secrets 0.2.2, ScadaBridge).
/// </para>
/// <para>
/// <b>Driver-role nodes only.</b> Admin-only nodes have no deployed configuration to cache,
@@ -170,7 +170,7 @@ public static class LocalDbSetup
/// <returns><c>true</c> when this node is configured to replicate.</returns>
public static bool ReplicationIsConfigured(IConfiguration configuration)
{
// Defined beside the alarm-historian drain gate's stricter predicate (#603, review R1 m3): every node
// Defined beside the alarm-historian drain gate's stricter predicate: every node
// the gate treats as sharing rows also captures, so the two never disagree in the harmful direction.
return Runtime.LocalDbReplicationPolicy.CapturesChanges(configuration);
}
@@ -17,6 +17,8 @@ internal static class RoleOverlay
/// The overlay filename suffix: the plain (non-cluster) roles, ordinal-sorted and joined with <c>-</c>, or
/// <see langword="null"/> when the node has none.
/// </summary>
/// <param name="gossipedRoles">The roles gossiped for this node.</param>
/// <returns>The suffix, or <see langword="null"/> when the node has no plain roles.</returns>
public static string? Suffix(IReadOnlyList<string> gossipedRoles)
{
var plain = gossipedRoles