docs: backfill XML documentation across 756 files

Adds <summary>, <param>, <typeparam>, and <inheritdoc/> tags to public
members surfaced by commentchecker — resolves 5,847 of 5,869 issues
(99.6%) across three /fixdocs passes.

src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/AlarmSurfaceInvoker.cs

@@ -29,6 +29,11 @@ public sealed class AlarmSurfaceInvoker
     private readonly IPerCallHostResolver? _hostResolver;
     private readonly string _defaultHost;
 
+    /// <summary>Initializes a new instance of the AlarmSurfaceInvoker class.</summary>
+    /// <param name="invoker">The capability invoker for resilience pipeline.</param>
+    /// <param name="alarmSource">The alarm source to invoke.</param>
+    /// <param name="defaultHost">The default host name for single-host scenarios.</param>
+    /// <param name="hostResolver">Optional per-call host resolver for multi-host dispatch.</param>
     public AlarmSurfaceInvoker(
         CapabilityInvoker invoker,
         IAlarmSource alarmSource,
@@ -52,6 +57,8 @@ public sealed class AlarmSurfaceInvoker
     ///     the driver's opaque handle together with its resolved host so <see cref="UnsubscribeAsync"/>
     ///     routes through the same host's pipeline that the subscription was created on.
     /// </summary>
+    /// <param name="sourceNodeIds">The source node IDs to subscribe to.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
     public async Task<IReadOnlyList<IAlarmSubscriptionHandle>> SubscribeAsync(
         IReadOnlyList<string> sourceNodeIds,
         CancellationToken cancellationToken)
@@ -80,6 +87,8 @@ public sealed class AlarmSurfaceInvoker
     ///     handles not created by this invoker so the method remains safe to call on any
     ///     <see cref="IAlarmSubscriptionHandle"/> implementation.
     /// </summary>
+    /// <param name="handle">The subscription handle to unsubscribe.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
     public ValueTask UnsubscribeAsync(IAlarmSubscriptionHandle handle, CancellationToken cancellationToken)
     {
         ArgumentNullException.ThrowIfNull(handle);
@@ -99,6 +108,8 @@ public sealed class AlarmSurfaceInvoker
     ///     AlarmAcknowledge pipeline (no-retry per decision #143 — an alarm-ack is not idempotent
     ///     at the plant-floor acknowledgement level even if the OPC UA spec permits re-issue).
     /// </summary>
+    /// <param name="acknowledgements">The alarm acknowledgement requests.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
     public async Task AcknowledgeAsync(
         IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements,
         CancellationToken cancellationToken)
@@ -139,6 +150,11 @@ public sealed class AlarmSurfaceInvoker
         return result;
     }
 
+    /// <summary>
+    ///     Wraps an <see cref="IAlarmSubscriptionHandle"/> returned by the driver with the
+    ///     resolved host name used when the subscription was created. <see cref="UnsubscribeAsync"/>
+    ///     unwraps this to route the unsubscribe through the same host's resilience pipeline.
+    /// </summary>
     /// <summary>
     ///     Wraps an <see cref="IAlarmSubscriptionHandle"/> returned by the driver with the
     ///     resolved host name used when the subscription was created. <see cref="UnsubscribeAsync"/>
@@ -146,8 +162,11 @@ public sealed class AlarmSurfaceInvoker
     /// </summary>
     private sealed class HostBoundHandle(IAlarmSubscriptionHandle inner, string host) : IAlarmSubscriptionHandle
     {
+        /// <summary>Gets the inner subscription handle.</summary>
         public IAlarmSubscriptionHandle Inner { get; } = inner;
+        /// <summary>Gets the resolved host name.</summary>
         public string Host { get; } = host;
+        /// <summary>Gets the diagnostic ID from the inner handle.</summary>
         public string DiagnosticId => Inner.DiagnosticId;
     }
 }

src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs

@@ -54,6 +54,10 @@ public sealed class CapabilityInvoker
 
     /// <summary>Execute a capability call returning a value, honoring the per-capability pipeline.</summary>
     /// <typeparam name="TResult">Return type of the underlying driver call.</typeparam>
+    /// <param name="capability">The driver capability being executed.</param>
+    /// <param name="hostName">The host name for logging and status tracking.</param>
+    /// <param name="callSite">The async function to execute.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
     public async ValueTask<TResult> ExecuteAsync<TResult>(
         DriverCapability capability,
         string hostName,
@@ -78,6 +82,10 @@ public sealed class CapabilityInvoker
     }
 
     /// <summary>Execute a void-returning capability call, honoring the per-capability pipeline.</summary>
+    /// <param name="capability">The driver capability being executed.</param>
+    /// <param name="hostName">The host name for logging and status tracking.</param>
+    /// <param name="callSite">The async function to execute.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
     public async ValueTask ExecuteAsync(
         DriverCapability capability,
         string hostName,
@@ -108,6 +116,11 @@ public sealed class CapabilityInvoker
     ///     decisions #44-45). If <c>true</c>, the call runs through the capability's pipeline which may
     ///     retry when the tier configuration permits.
     /// </summary>
+    /// <typeparam name="TResult">Return type of the underlying driver call.</typeparam>
+    /// <param name="hostName">The host name for logging and status tracking.</param>
+    /// <param name="isIdempotent">Whether the write operation is idempotent.</param>
+    /// <param name="callSite">The async function to execute.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
     public async ValueTask<TResult> ExecuteWriteAsync<TResult>(
         string hostName,
         bool isIdempotent,

src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/DriverResilienceOptions.cs

@@ -42,6 +42,8 @@ public sealed record DriverResilienceOptions
     ///     Look up the effective policy for a capability, falling back to tier defaults when no
     ///     override is configured. Never returns null.
     /// </summary>
+    /// <param name="capability">The driver capability to resolve the policy for.</param>
+    /// <returns>The effective CapabilityPolicy for the specified capability.</returns>
     /// <exception cref="KeyNotFoundException">
     ///     Thrown when neither the override map nor the tier defaults carry an entry for the
     ///     requested capability. The <c>TierDefaults_Cover_EveryCapability</c> invariant test
@@ -70,6 +72,8 @@ public sealed record DriverResilienceOptions
     ///     Stream A.2 specification. Retries skipped on <see cref="DriverCapability.Write"/> and
     ///     <see cref="DriverCapability.AlarmAcknowledge"/> regardless of tier.
     /// </summary>
+    /// <param name="tier">The driver tier to get defaults for.</param>
+    /// <returns>The default policy dictionary for the specified tier.</returns>
     public static IReadOnlyDictionary<DriverCapability, CapabilityPolicy> GetTierDefaults(DriverTier tier) =>
         tier switch
         {

src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/DriverResilienceOptionsParser.cs

@@ -47,6 +47,9 @@ public static class DriverResilienceOptionsParser
     ///     human-readable error message when the JSON was malformed (options still returned
     ///     = tier defaults).
     /// </summary>
+    /// <param name="tier">The driver tier for default resilience options.</param>
+    /// <param name="resilienceConfigJson">The optional JSON configuration string to parse.</param>
+    /// <param name="parseDiagnostic">An out parameter containing diagnostic information if parsing fails.</param>
     public static DriverResilienceOptions ParseOrDefaults(
         DriverTier tier,
         string? resilienceConfigJson,
@@ -117,16 +120,23 @@ public static class DriverResilienceOptionsParser
 
     private sealed class ResilienceConfigShape
     {
+        /// <summary>Gets or sets the maximum concurrent bulkhead requests.</summary>
         public int? BulkheadMaxConcurrent { get; set; }
+        /// <summary>Gets or sets the maximum bulkhead queue size.</summary>
         public int? BulkheadMaxQueue { get; set; }
+        /// <summary>Gets or sets the scheduled recycle interval in seconds.</summary>
         public int? RecycleIntervalSeconds { get; set; }
+        /// <summary>Gets or sets the per-capability resilience policies.</summary>
         public Dictionary<string, CapabilityPolicyShape>? CapabilityPolicies { get; set; }
     }
 
     private sealed class CapabilityPolicyShape
     {
+        /// <summary>Gets or sets the operation timeout in seconds.</summary>
         public int? TimeoutSeconds { get; set; }
+        /// <summary>Gets or sets the number of retry attempts.</summary>
         public int? RetryCount { get; set; }
+        /// <summary>Gets or sets the failure count threshold before the circuit breaker opens.</summary>
         public int? BreakerFailureThreshold { get; set; }
     }
 }

src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/DriverResiliencePipelineBuilder.cs

@@ -70,6 +70,8 @@ public sealed class DriverResiliencePipelineBuilder
     }
 
     /// <summary>Drop cached pipelines for one driver instance (e.g. on ResilienceConfig change). Test + Admin-reload use.</summary>
+    /// <param name="driverInstanceId">The driver instance ID whose pipelines should be invalidated.</param>
+    /// <returns>The number of pipelines removed.</returns>
     public int Invalidate(string driverInstanceId)
     {
         var removed = 0;

src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/DriverResilienceStatusTracker.cs

@@ -19,6 +19,9 @@ public sealed class DriverResilienceStatusTracker
     private readonly ConcurrentDictionary<StatusKey, ResilienceStatusSnapshot> _status = new();
 
     /// <summary>Record a Polly pipeline failure for <paramref name="hostName"/>.</summary>
+    /// <param name="driverInstanceId">The driver instance identifier.</param>
+    /// <param name="hostName">The host name.</param>
+    /// <param name="utcNow">The UTC timestamp of the failure event.</param>
     public void RecordFailure(string driverInstanceId, string hostName, DateTime utcNow)
     {
         var key = new StatusKey(driverInstanceId, hostName);
@@ -32,6 +35,9 @@ public sealed class DriverResilienceStatusTracker
     }
 
     /// <summary>Reset the consecutive-failure count on a successful pipeline execution.</summary>
+    /// <param name="driverInstanceId">The driver instance identifier.</param>
+    /// <param name="hostName">The host name.</param>
+    /// <param name="utcNow">The UTC timestamp of the success event.</param>
     public void RecordSuccess(string driverInstanceId, string hostName, DateTime utcNow)
     {
         var key = new StatusKey(driverInstanceId, hostName);
@@ -45,6 +51,9 @@ public sealed class DriverResilienceStatusTracker
     }
 
     /// <summary>Record a circuit-breaker open event.</summary>
+    /// <param name="driverInstanceId">The driver instance identifier.</param>
+    /// <param name="hostName">The host name.</param>
+    /// <param name="utcNow">The UTC timestamp of the breaker open event.</param>
     public void RecordBreakerOpen(string driverInstanceId, string hostName, DateTime utcNow)
     {
         var key = new StatusKey(driverInstanceId, hostName);
@@ -54,6 +63,9 @@ public sealed class DriverResilienceStatusTracker
     }
 
     /// <summary>Record a process recycle event (Tier C only).</summary>
+    /// <param name="driverInstanceId">The driver instance identifier.</param>
+    /// <param name="hostName">The host name.</param>
+    /// <param name="utcNow">The UTC timestamp of the recycle event.</param>
     public void RecordRecycle(string driverInstanceId, string hostName, DateTime utcNow)
     {
         var key = new StatusKey(driverInstanceId, hostName);
@@ -63,6 +75,11 @@ public sealed class DriverResilienceStatusTracker
     }
 
     /// <summary>Capture / update the MemoryTracking-supplied baseline + current footprint.</summary>
+    /// <param name="driverInstanceId">The driver instance identifier.</param>
+    /// <param name="hostName">The host name.</param>
+    /// <param name="baselineBytes">The baseline footprint in bytes.</param>
+    /// <param name="currentBytes">The current footprint in bytes.</param>
+    /// <param name="utcNow">The UTC timestamp of the footprint update.</param>
     public void RecordFootprint(string driverInstanceId, string hostName, long baselineBytes, long currentBytes, DateTime utcNow)
     {
         var key = new StatusKey(driverInstanceId, hostName);
@@ -87,6 +104,8 @@ public sealed class DriverResilienceStatusTracker
     ///     surface (a cheap stand-in for Polly bulkhead depth). Paired with
     ///     <see cref="RecordCallComplete"/>; callers use try/finally.
     /// </summary>
+    /// <param name="driverInstanceId">The driver instance identifier.</param>
+    /// <param name="hostName">The host name.</param>
     public void RecordCallStart(string driverInstanceId, string hostName)
     {
         var key = new StatusKey(driverInstanceId, hostName);
@@ -96,6 +115,8 @@ public sealed class DriverResilienceStatusTracker
     }
 
     /// <summary>Paired with <see cref="RecordCallStart"/> — decrements the in-flight counter.</summary>
+    /// <param name="driverInstanceId">The driver instance identifier.</param>
+    /// <param name="hostName">The host name.</param>
     public void RecordCallComplete(string driverInstanceId, string hostName)
     {
         var key = new StatusKey(driverInstanceId, hostName);
@@ -105,6 +126,8 @@ public sealed class DriverResilienceStatusTracker
     }
 
     /// <summary>Snapshot of a specific (instance, host) pair; null if no counters recorded yet.</summary>
+    /// <param name="driverInstanceId">The driver instance identifier.</param>
+    /// <param name="hostName">The host name.</param>
     public ResilienceStatusSnapshot? TryGet(string driverInstanceId, string hostName) =>
         _status.TryGetValue(new StatusKey(driverInstanceId, hostName), out var snapshot) ? snapshot : null;
 
@@ -118,11 +141,17 @@ public sealed class DriverResilienceStatusTracker
 /// <summary>Snapshot of the resilience counters for one <c>(DriverInstanceId, HostName)</c> pair.</summary>
 public sealed record ResilienceStatusSnapshot
 {
+    /// <summary>Gets the number of consecutive pipeline failures.</summary>
     public int ConsecutiveFailures { get; init; }
+    /// <summary>Gets the UTC timestamp of the last circuit-breaker open event, if any.</summary>
     public DateTime? LastBreakerOpenUtc { get; init; }
+    /// <summary>Gets the UTC timestamp of the last recycle event, if any.</summary>
     public DateTime? LastRecycleUtc { get; init; }
+    /// <summary>Gets the baseline process footprint in bytes.</summary>
     public long BaselineFootprintBytes { get; init; }
+    /// <summary>Gets the current process footprint in bytes.</summary>
     public long CurrentFootprintBytes { get; init; }
+    /// <summary>Gets the UTC timestamp when the counters were last updated.</summary>
     public DateTime LastSampledUtc { get; init; }
 
     /// <summary>