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/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbLegacy/AbLegacyDriver.cs

@@ -28,9 +28,23 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
     // observes the most recently written value.
     private volatile DriverHealth _health = new(DriverState.Unknown, null, null);
 
+    /// <summary>
+    ///     Occurs when data values change.
+    /// </summary>
     public event EventHandler<DataChangeEventArgs>? OnDataChange;
+
+    /// <summary>
+    ///     Occurs when host status changes.
+    /// </summary>
     public event EventHandler<HostStatusChangedEventArgs>? OnHostStatusChanged;
 
+    /// <summary>
+    ///     Initializes a new instance of the <see cref="AbLegacyDriver"/> class.
+    /// </summary>
+    /// <param name="options">The driver options.</param>
+    /// <param name="driverInstanceId">The driver instance identifier.</param>
+    /// <param name="tagFactory">The tag factory, or <c>null</c> to use the default.</param>
+    /// <param name="logger">The logger, or <c>null</c> to use the null logger.</param>
     public AbLegacyDriver(AbLegacyDriverOptions options, string driverInstanceId,
         IAbLegacyTagFactory? tagFactory = null,
         ILogger<AbLegacyDriver>? logger = null)
@@ -46,9 +60,22 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
                 OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, tagRef, snapshot)));
     }
 
+    /// <summary>
+    ///     Gets the driver instance identifier.
+    /// </summary>
     public string DriverInstanceId => _driverInstanceId;
+
+    /// <summary>
+    ///     Gets the driver type.
+    /// </summary>
     public string DriverType => "AbLegacy";
 
+    /// <summary>
+    ///     Initializes the driver asynchronously.
+    /// </summary>
+    /// <param name="driverConfigJson">The driver configuration JSON.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     public Task InitializeAsync(string driverConfigJson, CancellationToken cancellationToken)
     {
         _health = new DriverHealth(DriverState.Initializing, null, null);
@@ -121,12 +148,23 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
         return Task.CompletedTask;
     }
 
+    /// <summary>
+    ///     Reinitializes the driver asynchronously.
+    /// </summary>
+    /// <param name="driverConfigJson">The driver configuration JSON.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     public async Task ReinitializeAsync(string driverConfigJson, CancellationToken cancellationToken)
     {
         await ShutdownAsync(cancellationToken).ConfigureAwait(false);
         await InitializeAsync(driverConfigJson, cancellationToken).ConfigureAwait(false);
     }
 
+    /// <summary>
+    ///     Shuts down the driver asynchronously.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     public async Task ShutdownAsync(CancellationToken cancellationToken)
     {
         await _poll.DisposeAsync().ConfigureAwait(false);
@@ -142,16 +180,46 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
         _health = new DriverHealth(DriverState.Unknown, _health.LastSuccessfulRead, null);
     }
 
+    /// <summary>
+    ///     Gets the driver health status.
+    /// </summary>
+    /// <returns>The driver health status.</returns>
     public DriverHealth GetHealth() => _health;
+
+    /// <summary>
+    ///     Gets the memory footprint of the driver.
+    /// </summary>
+    /// <returns>The memory footprint in bytes.</returns>
     public long GetMemoryFootprint() => 0;
+
+    /// <summary>
+    ///     Flushes optional caches asynchronously.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     public Task FlushOptionalCachesAsync(CancellationToken cancellationToken) => Task.CompletedTask;
 
+    /// <summary>
+    ///     Gets the device count.
+    /// </summary>
     internal int DeviceCount => _devices.Count;
+
+    /// <summary>
+    ///     Gets the device state for the specified host address.
+    /// </summary>
+    /// <param name="hostAddress">The host address.</param>
+    /// <returns>The device state, or <c>null</c> if not found.</returns>
     internal DeviceState? GetDeviceState(string hostAddress) =>
         _devices.TryGetValue(hostAddress, out var s) ? s : null;
 
     // ---- IReadable ----
 
+    /// <summary>
+    ///     Reads data values asynchronously.
+    /// </summary>
+    /// <param name="fullReferences">The full references to read.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A list of data value snapshots.</returns>
     public async Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
         IReadOnlyList<string> fullReferences, CancellationToken cancellationToken)
     {
@@ -237,6 +305,12 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
 
     // ---- IWritable ----
 
+    /// <summary>
+    ///     Writes data values asynchronously.
+    /// </summary>
+    /// <param name="writes">The write requests.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A list of write results.</returns>
     public async Task<IReadOnlyList<WriteResult>> WriteAsync(
         IReadOnlyList<WriteRequest> writes, CancellationToken cancellationToken)
     {
@@ -326,6 +400,12 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
 
     // ---- ITagDiscovery ----
 
+    /// <summary>
+    ///     Discovers tags and populates the address space asynchronously.
+    /// </summary>
+    /// <param name="builder">The address space builder.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     public Task DiscoverAsync(IAddressSpaceBuilder builder, CancellationToken cancellationToken)
     {
         ArgumentNullException.ThrowIfNull(builder);
@@ -364,10 +444,23 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
 
     // ---- ISubscribable (polling overlay via shared engine) ----
 
+    /// <summary>
+    ///     Subscribes to data changes asynchronously.
+    /// </summary>
+    /// <param name="fullReferences">The full references to subscribe to.</param>
+    /// <param name="publishingInterval">The publishing interval.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A subscription handle.</returns>
     public Task<ISubscriptionHandle> SubscribeAsync(
         IReadOnlyList<string> fullReferences, TimeSpan publishingInterval, CancellationToken cancellationToken) =>
         Task.FromResult(_poll.Subscribe(fullReferences, publishingInterval));
 
+    /// <summary>
+    ///     Unsubscribes from data changes asynchronously.
+    /// </summary>
+    /// <param name="handle">The subscription handle.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     public Task UnsubscribeAsync(ISubscriptionHandle handle, CancellationToken cancellationToken)
     {
         _poll.Unsubscribe(handle);
@@ -376,6 +469,10 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
 
     // ---- IHostConnectivityProbe ----
 
+    /// <summary>
+    ///     Gets the host connectivity statuses.
+    /// </summary>
+    /// <returns>A list of host connectivity statuses.</returns>
     public IReadOnlyList<HostConnectivityStatus> GetHostStatuses() =>
         [.. _devices.Values.Select(s => new HostConnectivityStatus(s.Options.HostAddress, s.HostState, s.HostStateChangedUtc))];
 
@@ -462,6 +559,8 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
     ///             <see cref="DeviceCount"/> before relying on per-tag routing.</item>
     ///     </list>
     /// </summary>
+    /// <param name="fullReference">The full reference to resolve.</param>
+    /// <returns>The host address for the reference.</returns>
     public string ResolveHost(string fullReference)
     {
         if (_tagsByName.TryGetValue(fullReference, out var def))
@@ -638,6 +737,10 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
         _health = new DriverHealth(DriverState.Unknown, _health.LastSuccessfulRead, null);
     }
 
+    /// <summary>
+    ///     Disposes the driver asynchronously.
+    /// </summary>
+    /// <returns>A task representing the asynchronous disposal.</returns>
     public async ValueTask DisposeAsync() => await ShutdownAsync(CancellationToken.None).ConfigureAwait(false);
 
     internal sealed class DeviceState(
@@ -645,8 +748,19 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
         AbLegacyDeviceOptions options,
         AbLegacyPlcFamilyProfile profile)
     {
+        /// <summary>
+        ///     Gets the parsed host address.
+        /// </summary>
         public AbLegacyHostAddress ParsedAddress { get; } = parsedAddress;
+
+        /// <summary>
+        ///     Gets the device options.
+        /// </summary>
         public AbLegacyDeviceOptions Options { get; } = options;
+
+        /// <summary>
+        ///     Gets the PLC family profile.
+        /// </summary>
         public AbLegacyPlcFamilyProfile Profile { get; } = profile;
 
         /// <summary>
@@ -686,11 +800,21 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
         /// </summary>
         private readonly System.Collections.Concurrent.ConcurrentDictionary<string, SemaphoreSlim> _creationLocks = new(StringComparer.OrdinalIgnoreCase);
 
+        /// <summary>
+        ///     Gets or creates the creation lock for the specified key.
+        /// </summary>
+        /// <param name="key">The lock key.</param>
+        /// <returns>The semaphore slim for the key.</returns>
         public SemaphoreSlim GetCreationLock(string key) =>
             _creationLocks.GetOrAdd(key, _ => new SemaphoreSlim(1, 1));
 
         private readonly System.Collections.Concurrent.ConcurrentDictionary<string, SemaphoreSlim> _rmwLocks = new();
 
+        /// <summary>
+        ///     Gets or creates the read-modify-write lock for the specified parent name.
+        /// </summary>
+        /// <param name="parentName">The parent name.</param>
+        /// <returns>The semaphore slim for the parent.</returns>
         public SemaphoreSlim GetRmwLock(string parentName) =>
             _rmwLocks.GetOrAdd(parentName, _ => new SemaphoreSlim(1, 1));
 
@@ -705,13 +829,34 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
         ///     or value is never observed mid-update by another thread. Keyed by tag name, which
         ///     is also the <see cref="Runtimes"/> dictionary key.
         /// </summary>
+        /// <param name="tagName">The tag name.</param>
+        /// <returns>The semaphore slim for the tag.</returns>
         public SemaphoreSlim GetRuntimeLock(string tagName) =>
             _runtimeLocks.GetOrAdd(tagName, _ => new SemaphoreSlim(1, 1));
 
+        /// <summary>
+        ///     Gets the probe synchronization lock.
+        /// </summary>
         public object ProbeLock { get; } = new();
+
+        /// <summary>
+        ///     Gets or sets the host state.
+        /// </summary>
         public HostState HostState { get; set; } = HostState.Unknown;
+
+        /// <summary>
+        ///     Gets or sets the UTC time when the host state last changed.
+        /// </summary>
         public DateTime HostStateChangedUtc { get; set; } = DateTime.UtcNow;
+
+        /// <summary>
+        ///     Gets or sets the cancellation token source for the probe loop.
+        /// </summary>
         public CancellationTokenSource? ProbeCts { get; set; }
+
+        /// <summary>
+        ///     Gets or sets a value indicating whether the probe has been initialized.
+        /// </summary>
         public bool ProbeInitialized { get; set; }
 
         /// <summary>
@@ -725,6 +870,9 @@ public sealed class AbLegacyDriver : IDriver, IReadable, IWritable, ITagDiscover
         /// </summary>
         public bool FirstNonZeroStatusLogged { get; set; }
 
+        /// <summary>
+        ///     Disposes all cached tag runtimes.
+        /// </summary>
         public void DisposeRuntimes()
         {
             foreach (var r in Runtimes.Values) r.Dispose();