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/Core/ZB.MOM.WW.OtOpcUa.Configuration.Tests/ClusterAuditQueryTests.cs

@@ -51,6 +51,7 @@ public sealed class ClusterAuditQueryTests : IDisposable
 
     /// <summary>Structured rows (ClusterId null, NodeId set) for a node in the cluster are now
     /// visible, alongside the SP-path rows that stamp ClusterId directly.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Surfaces_both_clusterId_rows_and_structured_nodeId_rows()
     {
@@ -77,6 +78,7 @@ public sealed class ClusterAuditQueryTests : IDisposable
     }
 
     /// <summary>An audit row stamped with another cluster's ClusterId never appears.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Does_not_surface_other_cluster_rows()
     {
@@ -91,6 +93,7 @@ public sealed class ClusterAuditQueryTests : IDisposable
     }
 
     /// <summary>Respects the page-size cap, newest first.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Caps_to_page_size_newest_first()
     {

tests/Core/ZB.MOM.WW.OtOpcUa.Configuration.Tests/DriverHostStatusTests.cs

@@ -17,6 +17,7 @@ namespace ZB.MOM.WW.OtOpcUa.Configuration.Tests;
 public sealed class DriverHostStatusTests(SchemaComplianceFixture fixture)
 {
     /// <summary>Verifies that the composite key allows the same host across different nodes or drivers.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Composite_key_allows_same_host_across_different_nodes_or_drivers()
     {
@@ -58,6 +59,7 @@ public sealed class DriverHostStatusTests(SchemaComplianceFixture fixture)
     }
 
     /// <summary>Verifies that the upsert pattern updates existing records in place.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Upsert_pattern_for_same_key_updates_in_place()
     {
@@ -97,6 +99,7 @@ public sealed class DriverHostStatusTests(SchemaComplianceFixture fixture)
     }
 
     /// <summary>Verifies that the State enum is persisted as a string, not an integer.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task Enum_persists_as_string_not_int()
     {

tests/Core/ZB.MOM.WW.OtOpcUa.Configuration.Tests/GenerationSealedCacheTests.cs

@@ -33,6 +33,7 @@ public sealed class GenerationSealedCacheTests : IDisposable
         };
 
     /// <summary>Verifies that reading a snapshot on first boot with no existing snapshot throws.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task FirstBoot_NoSnapshot_ReadThrows()
     {
@@ -43,6 +44,7 @@ public sealed class GenerationSealedCacheTests : IDisposable
     }
 
     /// <summary>Verifies that sealed snapshots can be read back correctly.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SealThenRead_RoundTrips()
     {
@@ -58,6 +60,7 @@ public sealed class GenerationSealedCacheTests : IDisposable
     }
 
     /// <summary>Verifies that sealed files are marked read-only on disk.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SealedFile_IsReadOnly_OnDisk()
     {
@@ -71,6 +74,7 @@ public sealed class GenerationSealedCacheTests : IDisposable
     }
 
     /// <summary>Verifies that the current generation pointer advances when a new generation is sealed.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SealingTwoGenerations_PointerAdvances_ToLatest()
     {
@@ -84,6 +88,7 @@ public sealed class GenerationSealedCacheTests : IDisposable
     }
 
     /// <summary>Verifies that prior generation files are preserved after a new seal.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task PriorGenerationFile_Survives_AfterNewSeal()
     {
@@ -97,6 +102,7 @@ public sealed class GenerationSealedCacheTests : IDisposable
     }
 
     /// <summary>Verifies that reading a corrupt sealed file fails safely.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CorruptSealedFile_ReadFailsClosed()
     {
@@ -113,6 +119,7 @@ public sealed class GenerationSealedCacheTests : IDisposable
     }
 
     /// <summary>Verifies that reading with a missing sealed file fails safely.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task MissingSealedFile_ReadFailsClosed()
     {
@@ -129,6 +136,7 @@ public sealed class GenerationSealedCacheTests : IDisposable
     }
 
     /// <summary>Verifies that reading with a corrupt pointer file fails safely.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task CorruptPointerFile_ReadFailsClosed()
     {
@@ -143,6 +151,7 @@ public sealed class GenerationSealedCacheTests : IDisposable
     }
 
     /// <summary>Verifies that sealing the same generation twice is idempotent.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task SealSameGenerationTwice_IsIdempotent()
     {
@@ -155,6 +164,7 @@ public sealed class GenerationSealedCacheTests : IDisposable
     }
 
     /// <summary>Verifies that independent clusters do not interfere with each other.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     [Fact]
     public async Task IndependentClusters_DoNotInterfere()
     {

tests/Core/ZB.MOM.WW.OtOpcUa.Configuration.Tests/LdapGroupRoleMappingServiceTests.cs

@@ -34,6 +34,7 @@ public sealed class LdapGroupRoleMappingServiceTests : IDisposable
         };
 
     /// <summary>Verifies that Create sets Id and CreatedAtUtc.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Create_SetsId_AndCreatedAtUtc()
     {
@@ -47,6 +48,7 @@ public sealed class LdapGroupRoleMappingServiceTests : IDisposable
     }
 
     /// <summary>Verifies that Create rejects empty LDAP group.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Create_Rejects_EmptyLdapGroup()
     {
@@ -58,6 +60,7 @@ public sealed class LdapGroupRoleMappingServiceTests : IDisposable
     }
 
     /// <summary>Verifies that Create rejects system-wide mapping with ClusterId.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Create_Rejects_SystemWide_With_ClusterId()
     {
@@ -69,6 +72,7 @@ public sealed class LdapGroupRoleMappingServiceTests : IDisposable
     }
 
     /// <summary>Verifies that Create rejects non-system-wide mapping without ClusterId.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Create_Rejects_NonSystemWide_WithoutClusterId()
     {
@@ -80,6 +84,7 @@ public sealed class LdapGroupRoleMappingServiceTests : IDisposable
     }
 
     /// <summary>Verifies that GetByGroups returns only matching grants.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task GetByGroups_Returns_MatchingGrants_Only()
     {
@@ -96,6 +101,7 @@ public sealed class LdapGroupRoleMappingServiceTests : IDisposable
     }
 
     /// <summary>Verifies that GetByGroups returns empty when input is empty.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task GetByGroups_Empty_Input_ReturnsEmpty()
     {
@@ -108,6 +114,7 @@ public sealed class LdapGroupRoleMappingServiceTests : IDisposable
     }
 
     /// <summary>Verifies that ListAll orders results by group then cluster.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task ListAll_Orders_ByGroupThenCluster()
     {
@@ -125,6 +132,7 @@ public sealed class LdapGroupRoleMappingServiceTests : IDisposable
     }
 
     /// <summary>Verifies that Delete removes the matching row.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Delete_Removes_Matching_Row()
     {
@@ -138,6 +146,7 @@ public sealed class LdapGroupRoleMappingServiceTests : IDisposable
     }
 
     /// <summary>Verifies that Delete with unknown Id is a no-op.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Delete_Unknown_Id_IsNoOp()
     {
@@ -148,6 +157,7 @@ public sealed class LdapGroupRoleMappingServiceTests : IDisposable
     }
 
     /// <summary>Verifies that a system-wide row (IsSystemWide=true, ClusterId=null) appears in both ListAllAsync and GetByGroupsAsync.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task SystemWide_Row_AppearsIn_ListAll_And_GetByGroups()
     {

tests/Core/ZB.MOM.WW.OtOpcUa.Configuration.Tests/LiteDbConfigCacheTests.cs

@@ -24,6 +24,7 @@ public sealed class LiteDbConfigCacheTests : IDisposable
     };
 
     /// <summary>Verifies that payload is preserved through a write-then-read cycle.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Roundtrip_preserves_payload()
     {
@@ -38,6 +39,7 @@ public sealed class LiteDbConfigCacheTests : IDisposable
     }
 
     /// <summary>Verifies that GetMostRecentAsync returns the latest generation when multiple exist.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task GetMostRecent_returns_latest_when_multiple_generations_present()
     {
@@ -50,6 +52,7 @@ public sealed class LiteDbConfigCacheTests : IDisposable
     }
 
     /// <summary>Verifies that GetMostRecentAsync returns null for an unknown cluster.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task GetMostRecent_returns_null_for_unknown_cluster()
     {
@@ -58,6 +61,7 @@ public sealed class LiteDbConfigCacheTests : IDisposable
     }
 
     /// <summary>Verifies that Prune keeps the latest N generations and drops older ones.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Prune_keeps_latest_N_and_drops_older()
     {
@@ -81,6 +85,7 @@ public sealed class LiteDbConfigCacheTests : IDisposable
     }
 
     /// <summary>Verifies that writing the same cluster/generation twice replaces rather than duplicates.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task Put_same_cluster_generation_twice_replaces_not_duplicates()
     {
@@ -102,6 +107,7 @@ public sealed class LiteDbConfigCacheTests : IDisposable
     // callers could both observe `existing is null` and both Insert.
     // ------------------------------------------------------------------------------------
     /// <summary>Verifies that concurrent PutAsync calls for the same cluster and generation do not create duplicates.</summary>
+    /// <returns>A task that represents the asynchronous test operation.</returns>
     [Fact]
     public async Task PutAsync_concurrent_for_same_cluster_and_generation_does_not_duplicate()
     {

tests/Core/ZB.MOM.WW.OtOpcUa.Configuration.Tests/ResilientConfigReaderTests.cs

@@ -26,6 +26,7 @@ public sealed class ResilientConfigReaderTests : IDisposable
     }
 
     /// <summary>Verifies that successful central DB reads return value and mark fresh.</summary>
+    /// <returns>A task that represents the asynchronous test.</returns>
     [Fact]
     public async Task CentralDbSucceeds_ReturnsValue_MarksFresh()
     {
@@ -45,6 +46,7 @@ public sealed class ResilientConfigReaderTests : IDisposable
     }
 
     /// <summary>Verifies that exhausted retries fall back to cache and mark stale.</summary>
+    /// <returns>A task that represents the asynchronous test.</returns>
     [Fact]
     public async Task CentralDbFails_ExhaustsRetries_FallsBackToCache_MarksStale()
     {
@@ -78,6 +80,7 @@ public sealed class ResilientConfigReaderTests : IDisposable
     }
 
     /// <summary>Verifies that DB failure with unavailable cache throws.</summary>
+    /// <returns>A task that represents the asynchronous test.</returns>
     [Fact]
     public async Task CentralDbFails_AndCacheAlsoUnavailable_Throws()
     {
@@ -99,6 +102,7 @@ public sealed class ResilientConfigReaderTests : IDisposable
     }
 
     /// <summary>Verifies that cancellation is not retried.</summary>
+    /// <returns>A task that represents the asynchronous test.</returns>
     [Fact]
     public async Task Cancellation_NotRetried()
     {
@@ -133,6 +137,7 @@ public sealed class ResilientConfigReaderTests : IDisposable
     // ------------------------------------------------------------------------------------
 
     /// <summary>Verifies that command timeout TaskCanceledException falls back to cache.</summary>
+    /// <returns>A task that represents the asynchronous test.</returns>
     [Fact]
     public async Task CommandTimeout_TaskCanceledException_FallsBackToCache()
     {
@@ -163,6 +168,7 @@ public sealed class ResilientConfigReaderTests : IDisposable
     }
 
     /// <summary>Verifies that Polly timeout rejection falls back to cache.</summary>
+    /// <returns>A task that represents the asynchronous test.</returns>
     [Fact]
     public async Task PollyTimeout_TimeoutRejectedException_FallsBackToCache()
     {
@@ -201,6 +207,7 @@ public sealed class ResilientConfigReaderTests : IDisposable
     // ------------------------------------------------------------------------------------
 
     /// <summary>Verifies that fallback warnings do not log exceptions or password fragments.</summary>
+    /// <returns>A task that represents the asynchronous test.</returns>
     [Fact]
     public async Task FallbackWarning_does_not_log_full_exception_object_or_password_fragment()
     {
@@ -242,6 +249,7 @@ public sealed class ResilientConfigReaderTests : IDisposable
     }
 
     /// <summary>Verifies that caller cancellation propagates rather than falling back.</summary>
+    /// <returns>A task that represents the asynchronous test.</returns>
     [Fact]
     public async Task CallerCancellation_Propagates_NotFallback()
     {