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.FOCAS/IFocasClient.cs

@@ -17,6 +17,9 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.FOCAS;
 public interface IFocasClient : IDisposable
 {
     /// <summary>Open the FWLIB handle + TCP session. Idempotent.</summary>
+    /// <param name="address">The CNC host address and port.</param>
+    /// <param name="timeout">The connection timeout duration.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task ConnectAsync(FocasHostAddress address, TimeSpan timeout, CancellationToken cancellationToken);
 
     /// <summary>True when the FWLIB handle is valid + the socket is up.</summary>
@@ -27,6 +30,9 @@ public interface IFocasClient : IDisposable
     ///     <paramref name="type"/>. Returns a boxed .NET value + the OPC UA status mapped
     ///     through <see cref="FocasStatusMapper"/>.
     /// </summary>
+    /// <param name="address">The CNC memory address to read from.</param>
+    /// <param name="type">The FOCAS data type to read.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<(object? value, uint status)> ReadAsync(
         FocasAddress address,
         FocasDataType type,
@@ -36,6 +42,10 @@ public interface IFocasClient : IDisposable
     ///     Write <paramref name="value"/> to <paramref name="address"/>. Returns the mapped
     ///     OPC UA status (0 = Good).
     /// </summary>
+    /// <param name="address">The CNC memory address to write to.</param>
+    /// <param name="type">The FOCAS data type to write.</param>
+    /// <param name="value">The value to write.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<uint> WriteAsync(
         FocasAddress address,
         FocasDataType type,
@@ -46,6 +56,7 @@ public interface IFocasClient : IDisposable
     ///     Cheap health probe — e.g. <c>cnc_rdcncstat</c>. Returns <c>true</c> when the CNC
     ///     responds with any valid status.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<bool> ProbeAsync(CancellationToken cancellationToken);
 
     /// <summary>
@@ -54,6 +65,7 @@ public interface IFocasClient : IDisposable
     ///     active". IAlarmSource projection polls this at a configurable interval +
     ///     emits transitions (raise / clear) on the driver's <c>OnAlarmEvent</c>.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<IReadOnlyList<FocasActiveAlarm>> ReadAlarmsAsync(CancellationToken cancellationToken);
 
     // ---- Fixed-tree T1 (identity + axis discovery + fast-poll dynamic bundle) ----
@@ -63,6 +75,7 @@ public interface IFocasClient : IDisposable
     ///     subtree of the fixed-node surface. Callable once at session open; the
     ///     values don't change across the session.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<FocasSysInfo> GetSysInfoAsync(CancellationToken cancellationToken);
 
     /// <summary>
@@ -70,12 +83,14 @@ public interface IFocasClient : IDisposable
     ///     uses these to build the <c>Axes/{name}/</c> subtree and to index
     ///     <see cref="ReadDynamicAsync"/> calls.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<IReadOnlyList<FocasAxisName>> GetAxisNamesAsync(CancellationToken cancellationToken);
 
     /// <summary>
     ///     Read the CNC's configured spindle names via <c>cnc_rdspdlname</c>. Drives
     ///     the <c>Spindle/{name}/</c> subtree.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<IReadOnlyList<FocasSpindleName>> GetSpindleNamesAsync(CancellationToken cancellationToken);
 
     /// <summary>
@@ -84,6 +99,8 @@ public interface IFocasClient : IDisposable
     ///     distance-to-go) plus actual feed rate + actual spindle speed + alarm
     ///     flags + program / sequence numbers — one network round-trip per call.
     /// </summary>
+    /// <param name="axisIndex">The axis index to read dynamics for.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<FocasDynamicSnapshot> ReadDynamicAsync(int axisIndex, CancellationToken cancellationToken);
 
     // ---- Fixed-tree T2 (program + operation mode) ----
@@ -95,6 +112,7 @@ public interface IFocasClient : IDisposable
     ///     <see cref="ReadDynamicAsync"/> since program / mode transitions happen
     ///     on human-operator timescales.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<FocasProgramInfo> GetProgramInfoAsync(CancellationToken cancellationToken);
 
     // ---- Fixed-tree T3 (timers) ----
@@ -104,6 +122,8 @@ public interface IFocasClient : IDisposable
     ///     Cycle. Values are seconds — the managed side already converted the native
     ///     minute+msec representation so downstream nodes display uniform units.
     /// </summary>
+    /// <param name="kind">The timer kind to read.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<FocasTimer> GetTimerAsync(FocasTimerKind kind, CancellationToken cancellationToken);
 
     // ---- Fixed-tree T3.5 (servo meters) ----
@@ -113,6 +133,7 @@ public interface IFocasClient : IDisposable
     ///     Values are percentages (scaled by <c>10^Dec</c>). Empty list on a
     ///     disconnected session or unsupported CNC.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<IReadOnlyList<FocasServoLoad>> GetServoLoadsAsync(CancellationToken cancellationToken);
 
     // ---- Fixed-tree T3.6 (spindle meters) ----
@@ -123,12 +144,14 @@ public interface IFocasClient : IDisposable
     ///     disconnected session or when the CNC doesn't support the call (older
     ///     series like 16i may return EW_FUNC).
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<IReadOnlyList<int>> GetSpindleLoadsAsync(CancellationToken cancellationToken);
 
     /// <summary>
     ///     Read per-spindle maximum RPM values. Static configuration, fetched once at
     ///     bootstrap. Index alignment as per <see cref="GetSpindleLoadsAsync"/>.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     Task<IReadOnlyList<int>> GetSpindleMaxRpmsAsync(CancellationToken cancellationToken);
 }
 
@@ -180,6 +203,7 @@ public sealed record FocasAxisName(string Name, string Suffix)
 /// <summary>One configured spindle name (e.g. "S1").</summary>
 public sealed record FocasSpindleName(string Name, string Suffix1, string Suffix2, string Suffix3)
 {
+    /// <summary>Gets the display name — name + concatenated suffixes, trimmed.</summary>
     public string Display
     {
         get
@@ -210,6 +234,9 @@ public sealed record FocasProgramInfo(
 /// <summary>Human-readable text for the <see cref="FocasProgramInfo.Mode"/> integer.</summary>
 public static class FocasOpMode
 {
+    /// <summary>Converts a numeric operation mode to its text representation.</summary>
+    /// <param name="mode">The operation mode integer code.</param>
+    /// <returns>The text representation of the mode, or a fallback format if unknown.</returns>
     public static string ToText(int mode) => mode switch
     {
         0 => "MDI",
@@ -252,6 +279,8 @@ public sealed record FocasActiveAlarm(
 /// <summary>Factory for <see cref="IFocasClient"/>s. One client per configured device.</summary>
 public interface IFocasClientFactory
 {
+    /// <summary>Creates a new FOCAS client instance.</summary>
+    /// <returns>A new IFocasClient instance.</returns>
     IFocasClient Create();
 }
 
@@ -263,6 +292,9 @@ public interface IFocasClientFactory
 /// </summary>
 public sealed class UnimplementedFocasClientFactory : IFocasClientFactory
 {
+    /// <summary>Creates a new client instance (always throws NotSupportedException).</summary>
+    /// <returns>Never returns; always throws NotSupportedException.</returns>
+    /// <exception cref="NotSupportedException">Always thrown to indicate backend is not yet provisioned.</exception>
     public IFocasClient Create() => throw new NotSupportedException(
         "FOCAS driver backend is 'unimplemented'. Switch to 'Backend: \"wire\"' in driver config " +
         "once the CNC is provisioned — see docs/drivers/FOCAS.md.");