docs: complete XML doc comments via fixdocs (2757 to 131 findings)

Add missing <returns>/<param>/<summary>/<typeparam> tags and clean up
misused inheritdoc across 481 files so the documented API surface is
complete. Documentation-only (zero code lines changed). The 131 remaining
findings are inheritdoc-style warnings deliberately left to preserve
hand-written implementation rationale (plan-decision notes, race-condition
explanations).

tests/Server/ZB.MOM.WW.OtOpcUa.Security.Tests/AuthEndpointsIntegrationTests.cs

@@ -41,6 +41,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     private static CancellationToken Ct => TestContext.Current.CancellationToken;
 
     /// <summary>Initializes the test host and server.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async ValueTask InitializeAsync()
     {
         var dbName = $"auth-int-tests-{Guid.NewGuid():N}";
@@ -106,6 +107,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     }
 
     /// <summary>Disposes the test host and server.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async ValueTask DisposeAsync()
     {
         await _host.StopAsync(TestContext.Current.CancellationToken);
@@ -122,6 +124,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     };
 
     /// <summary>Tests that login with valid credentials returns 204 and sets cookie.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Login_with_valid_credentials_returns_204_and_sets_cookie()
     {
@@ -134,6 +137,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     }
 
     /// <summary>Tests that login with invalid credentials returns 401.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Login_with_invalid_credentials_returns_401()
     {
@@ -145,6 +149,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     }
 
     /// <summary>Tests that login when LDAP throws returns 503.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Login_when_ldap_throws_returns_503()
     {
@@ -156,6 +161,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     }
 
     /// <summary>Tests that ping anonymous returns 401.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Ping_anonymous_returns_401()
     {
@@ -166,6 +172,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     }
 
     /// <summary>Tests that ping after cookie login returns 200.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Ping_after_cookie_login_returns_200()
     {
@@ -181,6 +188,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     }
 
     /// <summary>Tests that token after cookie login returns jwt.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Token_after_cookie_login_returns_jwt()
     {
@@ -202,6 +210,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
 
     /// <summary>A system-wide DB row for a group the user holds grants an extra role on top of
     /// the appsettings baseline; the merged role surfaces in the issued JWT's Role claims.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Login_merges_db_role_grant_into_claims()
     {
@@ -238,6 +247,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     /// still SUCCEEDS but the user is granted ZERO role claims. They are authenticated (can prove
     /// identity) yet authorized for nothing role-gated until the mapper recovers — the safe
     /// fail-closed behaviour, not a fail-open with a stale role set.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Login_when_role_mapper_throws_signs_in_with_no_role_claims()
     {
@@ -307,6 +317,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     /// Also asserts that the old short-name literals "Username" and "DisplayName" are NOT emitted
     /// (the pre-Task-1.5 strings that would indicate the migration was incomplete).
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Login_emits_canonical_ZbClaimTypes_on_cookie_principal()
     {
@@ -367,6 +378,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     /// <see cref="JwtTokenService.RoleClaimType"/> docs for the rationale and the caveat that
     /// applies if a JwtBearer scheme is ever added).
     /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Token_payload_uses_canonical_zb_claim_keys()
     {
@@ -420,6 +432,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     }
 
     /// <summary>Tests that logout clears the cookie.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Logout_clears_the_cookie()
     {
@@ -439,6 +452,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     }
 
     /// <summary>Anonymous browser GET of a protected route redirects to /login with a ReturnUrl.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Root_anonymous_browser_GET_redirects_to_login()
     {
@@ -457,6 +471,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     /// via the <c>X-Requested-With</c> header — the ASP.NET cookie handler's IsAjaxRequest
     /// heuristic). The framework still writes a <c>Location</c> header alongside the 401;
     /// AJAX clients ignore it.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Root_anonymous_xhr_GET_returns_401()
     {
@@ -479,11 +494,7 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
 
     private sealed class StubLdapAuthService : ILdapAuthService
     {
-        /// <summary>Authenticates a user asynchronously using the stub service.</summary>
-        /// <param name="username">The username to authenticate.</param>
-        /// <param name="password">The password to verify.</param>
-        /// <param name="ct">The cancellation token.</param>
-        /// <returns>The authentication result.</returns>
+        /// <inheritdoc />
         public Task<LdapAuthResult> AuthenticateAsync(string username, string password, CancellationToken ct = default)
         {
             if (username == "ldap-down")
@@ -517,10 +528,12 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
     /// </summary>
     private sealed class StubLdapGroupRoleMappingService : ILdapGroupRoleMappingService
     {
+        /// <summary>Gets the seeded group-to-role mapping rows available for lookup.</summary>
         public List<LdapGroupRoleMapping> Rows { get; } = [];
+        /// <summary>Gets or sets a value indicating whether the service should simulate a fault.</summary>
         public bool Throws { get; set; }
 
-        /// <summary>Returns seeded rows whose group matches one of <paramref name="ldapGroups"/>.</summary>
+        /// <inheritdoc />
         public Task<IReadOnlyList<LdapGroupRoleMapping>> GetByGroupsAsync(
             IEnumerable<string> ldapGroups, CancellationToken cancellationToken)
         {
@@ -531,15 +544,15 @@ public sealed class AuthEndpointsIntegrationTests : IAsyncLifetime
             return Task.FromResult(matched);
         }
 
-        /// <summary>Not exercised by these tests.</summary>
+        /// <inheritdoc />
         public Task<IReadOnlyList<LdapGroupRoleMapping>> ListAllAsync(CancellationToken cancellationToken) =>
             throw new NotSupportedException();
 
-        /// <summary>Not exercised by these tests.</summary>
+        /// <inheritdoc />
         public Task<LdapGroupRoleMapping> CreateAsync(LdapGroupRoleMapping row, CancellationToken cancellationToken) =>
             throw new NotSupportedException();
 
-        /// <summary>Not exercised by these tests.</summary>
+        /// <inheritdoc />
         public Task DeleteAsync(Guid id, CancellationToken cancellationToken) =>
             throw new NotSupportedException();
     }