docs(src): add missing XML docs and strip tracking-ID comments

Sweep of 203 source files resolving CommentChecker findings: add
<summary>/<param>/<returns>/<inheritdoc> where missing, and remove
resolved task/issue tracking markers (Tests-NNN, Worker-NNN, Server-NNN,
Task N) from code comments. Comment/doc-only — no logic changes.
Server+Tests build clean under TreatWarningsAsErrors.
This commit is contained in:
Joseph Doherty
2026-07-07 14:09:49 -04:00
parent 8914472706
commit fca978de07
203 changed files with 1834 additions and 1383 deletions
@@ -20,6 +20,8 @@ namespace ZB.MOM.WW.MxGateway.Tests.Gateway.Dashboard;
public sealed class DashboardAuthenticatorTests
{
/// <summary>A blank username is rejected without touching the LDAP provider.</summary>
/// <param name="username">The blank/whitespace/null username under test.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(null)]
[InlineData("")]
@@ -40,6 +42,7 @@ public sealed class DashboardAuthenticatorTests
}
/// <summary>A blank password is rejected without touching the LDAP provider.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AuthenticateAsync_BlankPassword_FailsWithoutCallingLdap()
{
@@ -60,6 +63,8 @@ public sealed class DashboardAuthenticatorTests
/// A failed LDAP outcome (any failure bucket, including <see cref="LdapAuthFailure.Disabled"/>)
/// maps to the generic dashboard failure without leaking the raw password.
/// </summary>
/// <param name="failure">The LDAP failure bucket under test.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(LdapAuthFailure.Disabled)]
[InlineData(LdapAuthFailure.BadCredentials)]
@@ -87,6 +92,7 @@ public sealed class DashboardAuthenticatorTests
/// name (ClaimTypes.Name), and the username (ClaimTypes.NameIdentifier), under the
/// dashboard authentication scheme.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AuthenticateAsync_Success_BuildsPrincipalWithExpectedClaims()
{
@@ -127,11 +133,12 @@ public sealed class DashboardAuthenticatorTests
}
/// <summary>
/// Task 1.5: the principal emits canonical ZbClaimTypes.Username ("zb:username") with
/// The principal emits canonical ZbClaimTypes.Username ("zb:username") with
/// the login username, ZbClaimTypes.Role (= ClaimTypes.Role) for each resolved role, and
/// ZbClaimTypes.DisplayName ("zb:displayname") with the display name — while keeping
/// ClaimTypes.NameIdentifier, ClaimTypes.Name, and mxgateway:ldap_group claims intact.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AuthenticateAsync_Success_EmitsCanonicalZbClaims()
{
@@ -183,6 +190,7 @@ public sealed class DashboardAuthenticatorTests
/// When the user authenticates but none of their groups map to a dashboard role,
/// the login is denied (the long-standing "no roles matched → denied" rule).
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AuthenticateAsync_NoRolesMatched_DeniesLogin()
{
@@ -216,6 +224,7 @@ public sealed class DashboardAuthenticatorTests
/// for the realistic (already-short) group shape.
/// </para>
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AuthenticateAsync_GroupAsDistinguishedNameFromService_ResolvesRoleAndSurfacesServiceValue()
{
@@ -243,6 +252,7 @@ public sealed class DashboardAuthenticatorTests
}
/// <summary>The (already-trimmed) username from the LDAP result flows onto the principal.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AuthenticateAsync_UsesUsernameFromLdapResult()
{
@@ -296,10 +306,17 @@ public sealed class DashboardAuthenticatorTests
/// </summary>
private sealed class FakeLdapAuthService(LdapAuthResult result) : ILdapAuthService
{
/// <summary>Gets a value indicating whether <see cref="AuthenticateAsync"/> was invoked.</summary>
public bool WasCalled { get; private set; }
/// <summary>Gets the username passed to the most recent <see cref="AuthenticateAsync"/> call.</summary>
public string? LastUsername { get; private set; }
/// <summary>Records the call and returns the configured fixed result.</summary>
/// <param name="username">The username to authenticate.</param>
/// <param name="password">The password to authenticate.</param>
/// <param name="ct">Token to observe for cancellation.</param>
/// <returns>The fixed <see cref="LdapAuthResult"/> configured for this fake.</returns>
public Task<LdapAuthResult> AuthenticateAsync(string username, string password, CancellationToken ct)
{
WasCalled = true;