docs: strip task-tracking IDs from code comments and fill missing XML docs

Tracking IDs are review bookkeeping that rots in shipped source; the rationale they tagged is kept. Comment-only change (CommentChecker 458 -> 16 false positives).

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayClientCliTests.cs

@@ -134,6 +134,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>Verifies that write-secured builds a WriteSecured command with the value and user ids.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_WriteSecured_BuildsWriteSecuredCommand()
     {
@@ -178,6 +179,7 @@ public sealed class MxGatewayClientCliTests
     /// Verifies that authenticate-user builds an AuthenticateUser command sourcing the
     /// credential from the flag, and that the credential never appears in stdout/stderr.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_AuthenticateUser_BuildsCommandAndDoesNotEchoCredential()
     {
@@ -218,9 +220,10 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>
-    /// CLI-04: a surfaced error for authenticate-user must have the credential
+    /// Verifies that a surfaced error for authenticate-user must have the credential
     /// redacted (never echoed to stderr), mirroring the API-key redaction seam.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task RunAsync_AuthenticateUser_ErrorOutput_RedactsCredential()
     {
@@ -248,7 +251,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>
-    /// CLI-45: <c>--password</c> is the primary credential flag, matching the other
+    /// <c>--password</c> is the primary credential flag, matching the other
     /// four CLIs. The credential reaches the wire but never stdout/stderr.
     /// </summary>
     /// <returns>A task that represents the asynchronous operation.</returns>
@@ -290,10 +293,12 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>
-    /// CLI-45: the credential is read from the environment variable named by
+    /// the credential is read from the environment variable named by
     /// <c>--password-env</c>, whose default is the canonical
     /// <c>MXGATEWAY_VERIFY_PASSWORD</c> shared by all five CLIs.
     /// </summary>
+    /// <param name="passwordEnvArgument">The value passed to <c>--password-env</c>, or null to use the default.</param>
+    /// <param name="environmentName">The environment variable that holds the credential.</param>
     /// <returns>A task that represents the asynchronous operation.</returns>
     [Theory]
     [InlineData(null, "MXGATEWAY_VERIFY_PASSWORD")]
@@ -340,7 +345,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>
-    /// CLI-45: the pre-rename names stay usable for one release — the deprecated
+    /// the pre-rename names stay usable for one release — the deprecated
     /// <c>--verify-user-password</c> flag and the deprecated
     /// <c>MXGATEWAY_VERIFY_USER_PASSWORD</c> environment variable both still resolve.
     /// </summary>
@@ -413,7 +418,7 @@ public sealed class MxGatewayClientCliTests
     }
 
     /// <summary>
-    /// CLI-45: a missing or empty credential fails fast before the invoke — the CLI
+    /// a missing or empty credential fails fast before the invoke — the CLI
     /// never sends a fabricated empty password to the wire. The error names the flag
     /// and the environment variable, never a value.
     /// </summary>
@@ -463,6 +468,9 @@ public sealed class MxGatewayClientCliTests
         private readonly string _name;
         private readonly string? _original;
 
+        /// <summary>Sets the environment variable and remembers its original value.</summary>
+        /// <param name="name">The environment variable name.</param>
+        /// <param name="value">The temporary value, or null to clear it.</param>
         public EnvironmentVariableScope(string name, string? value)
         {
             _name = name;
@@ -470,6 +478,7 @@ public sealed class MxGatewayClientCliTests
             Environment.SetEnvironmentVariable(name, value);
         }
 
+        /// <summary>Restores the original environment variable value.</summary>
         public void Dispose()
         {
             Environment.SetEnvironmentVariable(_name, _original);
@@ -588,7 +597,7 @@ public sealed class MxGatewayClientCliTests
 
     /// <summary>
     ///     Verifies stream-events renders the ReplayGap sentinel as the typed cross-CLI row —
-    ///     numeric cursors under a replayGap key — instead of the raw sentinel MxEvent (NEXT-02).
+    ///     numeric cursors under a replayGap key — instead of the raw sentinel MxEvent.
     /// </summary>
     /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayClientSessionTests.cs

@@ -228,6 +228,7 @@ public sealed class MxGatewayClientSessionTests
     /// <see cref="MxEventStreamItem"/> with the gap populated, while normal
     /// events pass through unchanged with IsReplayGap false.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task StreamEventItemsAsync_SurfacesReplayGapSentinel()
     {
@@ -430,6 +431,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that unregister builds an unregister command with the server handle.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task UnregisterAsync_BuildsUnregisterCommand()
     {
@@ -451,6 +453,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that advise-supervisory builds the supervisory advise command.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AdviseSupervisoryAsync_BuildsAdviseSupervisoryCommand()
     {
@@ -473,6 +476,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that add-buffered-item returns the item handle from the typed reply.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AddBufferedItemAsync_BuildsCommandAndReturnsItemHandle()
     {
@@ -498,6 +502,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that set-buffered-update-interval builds the command with the interval.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SetBufferedUpdateIntervalAsync_BuildsCommandWithInterval()
     {
@@ -520,6 +525,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that suspend builds the command and returns the reply status.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SuspendAsync_BuildsCommandAndReturnsStatus()
     {
@@ -545,6 +551,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that activate builds the command and returns the reply status.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task ActivateAsync_BuildsCommandAndReturnsStatus()
     {
@@ -568,6 +575,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that write-secured builds a WriteSecured command with value and user ids.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task WriteSecuredAsync_BuildsWriteSecuredCommand()
     {
@@ -598,6 +606,7 @@ public sealed class MxGatewayClientSessionTests
     /// natively. The client must surface that scripted failure (as an
     /// <see cref="MxAccessException"/>) rather than pre-validating it away.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task WriteSecuredAsync_SurfacesNativeFailureWhenNotAuthenticated()
     {
@@ -621,6 +630,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that write-secured2 builds a WriteSecured2 command with value and timestamp.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task WriteSecured2Async_BuildsWriteSecured2Command()
     {
@@ -647,6 +657,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that authenticate-user builds the command and returns the resolved user id.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AuthenticateUserAsync_BuildsCommandAndReturnsUserId()
     {
@@ -675,6 +686,7 @@ public sealed class MxGatewayClientSessionTests
     /// must never contain the credential — the error path is built only from
     /// reply-derived diagnostics, not the request payload.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AuthenticateUserAsync_FailureDoesNotLeakCredentialInErrorMessage()
     {
@@ -698,6 +710,7 @@ public sealed class MxGatewayClientSessionTests
     }
 
     /// <summary>Verifies that archestra-user-to-id builds the command and returns the resolved user id.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task ArchestraUserToIdAsync_BuildsCommandAndReturnsUserId()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewaySecretRedactionTests.cs

@@ -8,6 +8,7 @@ namespace ZB.MOM.WW.MxGateway.Client.Tests;
 /// </summary>
 public sealed class MxGatewaySecretRedactionTests
 {
+    /// <summary>Test: Redact replaces every occurrence of secret.</summary>
     [Fact]
     public void Redact_ReplacesEveryOccurrenceOfSecret()
     {
@@ -19,6 +20,7 @@ public sealed class MxGatewaySecretRedactionTests
         Assert.Equal("pw=<redacted> retry pw=<redacted> again <redacted>", result);
     }
 
+    /// <summary>Test: Redact scrubs both secrets when one is substring of the other.</summary>
     [Fact]
     public void Redact_ScrubsBothSecretsWhenOneIsSubstringOfTheOther()
     {
@@ -33,6 +35,7 @@ public sealed class MxGatewaySecretRedactionTests
         Assert.DoesNotContain("secret", result, StringComparison.Ordinal);
     }
 
+    /// <summary>Test: Redact with null secrets array returns message unchanged.</summary>
     [Fact]
     public void Redact_WithNullSecretsArray_ReturnsMessageUnchanged()
     {
@@ -43,6 +46,7 @@ public sealed class MxGatewaySecretRedactionTests
         Assert.Equal(message, result);
     }
 
+    /// <summary>Test: Redact with empty secrets array returns message unchanged.</summary>
     [Fact]
     public void Redact_WithEmptySecretsArray_ReturnsMessageUnchanged()
     {
@@ -53,6 +57,7 @@ public sealed class MxGatewaySecretRedactionTests
         Assert.Equal(message, result);
     }
 
+    /// <summary>Test: Redact ignores whitespace only secret.</summary>
     [Fact]
     public void Redact_IgnoresWhitespaceOnlySecret()
     {
@@ -64,6 +69,7 @@ public sealed class MxGatewaySecretRedactionTests
         Assert.Equal(message, result);
     }
 
+    /// <summary>Test: Redacted preserves concrete subtype and does not chain secret bearing original.</summary>
     [Fact]
     public void Redacted_PreservesConcreteSubtypeAndDoesNotChainSecretBearingOriginal()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewaySessionReplyContractTests.cs

@@ -4,15 +4,16 @@ using ZB.MOM.WW.MxGateway.Contracts.Proto;
 namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
 /// <summary>
-/// Tests for the credential-scrub (CLI-40) and malformed-reply (CLI-41) contracts on the
+/// Tests for the credential-scrub and malformed-reply contracts on the
 /// credential and id-returning session helpers, driven from shared behavior fixtures.
 /// </summary>
 public sealed class MxGatewaySessionReplyContractTests
 {
     /// <summary>
-    /// CLI-40: when MXAccess echoes the submitted credential back in its failure diagnostic,
+    /// Verifies that when MXAccess echoes the submitted credential back in its failure diagnostic,
     /// the surfaced exception message must scrub it to the library redaction marker.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AuthenticateUserAsync_RedactsEchoedCredentialInFailureMessage()
     {
@@ -33,13 +34,14 @@ public sealed class MxGatewaySessionReplyContractTests
     }
 
     /// <summary>
-    /// CLI-40: the redacted exception must not leak the echoed credential through any structured
+    /// Verifies that the redacted exception must not leak the echoed credential through any structured
     /// accessor either — <see cref="MxAccessException.Reply"/> (protocol message, diagnostic
     /// message, and each MXSTATUS_PROXY diagnostic text) and <see cref="MxGatewayException.Statuses"/>
     /// all carry the server-echoed credential verbatim before the fix. Both the OK+negative-HRESULT
     /// and the MXACCESS_FAILURE reply route to <see cref="MxAccessException"/>, so both must scrub.
     /// </summary>
     /// <param name="fixture">The echoed-credential reply fixture to drive.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Theory]
     [InlineData("authenticate-user.echoed-credential.reply.json")]
     [InlineData("authenticate-user.echoed-credential-mxaccess-failure.reply.json")]
@@ -71,9 +73,10 @@ public sealed class MxGatewaySessionReplyContractTests
     }
 
     /// <summary>
-    /// CLI-41: an OK reply that carries neither the typed AuthenticateUser payload nor an
+    /// Verifies that an OK reply that carries neither the typed AuthenticateUser payload nor an
     /// int32 return_value is a malformed reply, surfaced as a typed exception rather than an NRE.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AuthenticateUserAsync_MissingPayloadAndReturnValue_ThrowsMalformedReply()
     {
@@ -87,9 +90,10 @@ public sealed class MxGatewaySessionReplyContractTests
     }
 
     /// <summary>
-    /// CLI-41: an OK reply that omits the typed payload but carries an int32 return_value
+    /// Verifies that an OK reply that omits the typed payload but carries an int32 return_value
     /// resolves to that return value.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AuthenticateUserAsync_ReturnValueOnly_ResolvesReturnValue()
     {
@@ -104,9 +108,10 @@ public sealed class MxGatewaySessionReplyContractTests
     }
 
     /// <summary>
-    /// CLI-41: the AddBufferedItem fallback shares the malformed-reply contract — an OK reply
+    /// Verifies that the AddBufferedItem fallback shares the malformed-reply contract — an OK reply
     /// with neither a typed item handle nor an int32 return_value throws the typed exception.
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task AddBufferedItemAsync_MissingPayloadAndReturnValue_ThrowsMalformedReply()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxStatusProxyExtensionsTests.cs

@@ -32,6 +32,9 @@ public sealed class MxStatusProxyExtensionsTests
     }
 
     /// <summary>Verifies that the raw success member never overrides the authoritative category.</summary>
+    /// <param name="category">The status category under test.</param>
+    /// <param name="success">The raw success member, which must not influence the result.</param>
+    /// <param name="expected">The expected <c>IsSuccess</c> result.</param>
     [Theory]
     [InlineData(MxStatusCategory.Ok, 0, true)]
     [InlineData(MxStatusCategory.Ok, 1, true)]

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/WireFakeGatewayServer.cs

@@ -96,7 +96,8 @@ internal sealed class WireFakeGatewayServer : IAsyncDisposable
             DefaultCallTimeout = TimeSpan.FromSeconds(30),
         });
 
-    /// <inheritdoc />
+    /// <summary>Stops and disposes the underlying web application.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async ValueTask DisposeAsync()
     {
         await _app.StopAsync().ConfigureAwait(false);