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).
2026-06-03 12:34:34 -04:00
parent c6d9b20d9f
commit bd6c0b4d3d
481 changed files with 2550 additions and 1668 deletions
@@ -68,6 +68,7 @@ internal sealed class FakeSidecarServer : IAsyncDisposable
    public string PipeName => _pipeName;

    /// <summary>Starts the fake sidecar server asynchronously.</summary>
+    /// <returns>A task that completes once the server listener is ready to accept connections.</returns>
    public Task StartAsync()
    {
        _loop = Task.Run(() => RunAsync(_cts.Token));
@@ -194,6 +195,7 @@ internal sealed class FakeSidecarServer : IAsyncDisposable
    }

    /// <summary>Releases all resources used by the fake sidecar server.</summary>
+    /// <returns>A value task that represents the asynchronous dispose operation.</returns>
    public async ValueTask DisposeAsync()
    {
        _cts.Cancel();
@@ -29,6 +29,7 @@ public sealed class WonderwareHistorianClientTests
        CallTimeout: TimeSpan.FromSeconds(2));

    /// <summary>Verifies that ReadRawAsync round-trips samples and maps quality bytes to OPC UA status codes.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReadRawAsync_RoundTripsSamples_AndMapsQualityByteToOpcUaStatusCode()
    {
@@ -71,6 +72,7 @@ public sealed class WonderwareHistorianClientTests
    }

    /// <summary>Verifies that ReadProcessedAsync maps null buckets to BadNoData status.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReadProcessedAsync_NullBuckets_MapToBadNoData()
    {
@@ -103,6 +105,7 @@ public sealed class WonderwareHistorianClientTests
    }

    /// <summary>Verifies that ReadAtTimeAsync preserves timestamp order.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReadAtTimeAsync_PreservesTimestampOrder()
    {
@@ -131,6 +134,7 @@ public sealed class WonderwareHistorianClientTests
    }

    /// <summary>Verifies that ReadAtTimeAsync aligns by timestamp and fills gaps with bad status.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReadAtTimeAsync_PartialAndReorderedReply_AlignsByTimestamp_AndFillsGapsAsBad()
    {
@@ -185,6 +189,7 @@ public sealed class WonderwareHistorianClientTests
    }

    /// <summary>Verifies that ReadEventsAsync preserves event field values.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReadEventsAsync_PreservesEventFields()
    {
@@ -223,6 +228,7 @@ public sealed class WonderwareHistorianClientTests
    }

    /// <summary>Verifies that ReadRawAsync throws InvalidOperationException on server errors.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReadRawAsync_ServerError_ThrowsInvalidOperation()
    {
@@ -241,6 +247,7 @@ public sealed class WonderwareHistorianClientTests
    }

    /// <summary>Verifies that WriteBatchAsync maps per-event results to acknowledge or retry outcomes.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task WriteBatchAsync_PerEventOk_MapsToAckOrRetryPlease()
    {
@@ -270,6 +277,7 @@ public sealed class WonderwareHistorianClientTests
    }

    /// <summary>Verifies that WriteBatchAsync returns retry outcomes for whole call failures.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task WriteBatchAsync_WholeCallFailure_ReturnsRetryPleaseForEveryEvent()
    {
@@ -300,6 +308,7 @@ public sealed class WonderwareHistorianClientTests
    }

    /// <summary>Verifies that Hello handshake throws UnauthorizedAccessException on secret mismatch.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Hello_BadSecret_ThrowsUnauthorizedAccess()
    {
@@ -315,6 +324,7 @@ public sealed class WonderwareHistorianClientTests
    }

    /// <summary>Verifies that the client retries after a transport drop.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task Reconnect_AfterTransportDrop_RetriesOnce()
    {
@@ -345,6 +355,7 @@ public sealed class WonderwareHistorianClientTests
    }

    /// <summary>Verifies that GetHealthSnapshot tracks success and failure counts.</summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task GetHealthSnapshot_TracksSuccessAndFailureCounts()
    {
@@ -381,6 +392,7 @@ public sealed class WonderwareHistorianClientTests
    ///     (2) A transport drop during a write (the catch path in WriteBatchAsync) must return
    ///     RetryPlease for every event in the batch — never throw, never PermanentFail.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task WriteBatchAsync_TransportDropDuringWrite_ReturnsRetryPleaseForEveryEvent()
    {
@@ -413,6 +425,7 @@ public sealed class WonderwareHistorianClientTests
    ///     (3) When both the first attempt and the single retry fail (the "second attempt also
    ///     fails" path in InvokeAsync), the exception propagates to the caller.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task InvokeAsync_BothAttemptsFailTransport_PropagatesException()
    {
@@ -436,6 +449,7 @@ public sealed class WonderwareHistorianClientTests
    ///     (4) A stalled sidecar that never sends a reply must cause an
    ///     <see cref="OperationCanceledException"/> within the configured CallTimeout.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReadRawAsync_StalledSidecar_TimesOutWithOperationCanceledException()
    {
@@ -466,6 +480,7 @@ public sealed class WonderwareHistorianClientTests
    ///     <see cref="NotSupportedException"/> because Wonderware AnalogSummary has no Total
    ///     aggregate column.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReadProcessedAsync_TotalAggregate_ThrowsNotSupported()
    {
@@ -486,6 +501,7 @@ public sealed class WonderwareHistorianClientTests
    ///     expect (e.g. ReadRawReply where ReadAtTimeReply was expected), the client must throw
    ///     <see cref="InvalidDataException"/>.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task ReadRawAsync_SidecarRepliesWithWrongKind_ThrowsInvalidDataException()
    {
@@ -513,6 +529,7 @@ public sealed class WonderwareHistorianClientTests
    ///     a future regression to the "RecordSuccess then undo via ReclassifySuccessAsFailure"
    ///     dance is caught.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task GetHealthSnapshot_SidecarFailure_NeverInflatesSuccessCounter()
    {
@@ -544,6 +561,7 @@ public sealed class WonderwareHistorianClientTests
    ///     channel serializes calls, so the test is observable: each completed query strictly
    ///     increments either successes or failures by one.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    [Fact]
    public async Task GetHealthSnapshot_ConcurrentCallsAndReads_CountersAreInternallyConsistent()
    {