docs: complete XML doc coverage (returns, summaries, inheritdoc)

Resolve all 622 issues flagged by the enhanced CommentChecker: add missing <returns> tags (incl. the standard phrasing on non-generic Task methods), add missing <summary> tags, and replace misused/redundant <inheritdoc/> on members that override or implement nothing with real documentation. Documentation-only — no behavior change; solution builds clean.
2026-06-03 11:39:32 -04:00
parent a050170414
commit eabf270d71
208 changed files with 867 additions and 114 deletions
@@ -35,6 +35,10 @@ public sealed class NotificationForwarder
    private readonly TimeSpan _forwardTimeout;
    private readonly ILogger<NotificationForwarder> _logger;

+    /// <summary>
+    /// Initializes a new <see cref="NotificationForwarder"/> that forwards buffered
+    /// notifications to the central cluster via the site communication actor.
+    /// </summary>
    /// <param name="siteCommunicationActor">
    /// The site communication actor. It forwards a <see cref="NotificationSubmit"/> to
    /// central via the registered ClusterClient and replies with the
@@ -69,6 +73,7 @@ public sealed class NotificationForwarder
    /// non-accepted ack or an Ask timeout/failure so the engine retries.
    /// </summary>
    /// <param name="message">The buffered store-and-forward message to deliver to central.</param>
+    /// <returns>A task that resolves to <c>true</c> when central accepts (or the payload is corrupt and discarded); throws on a transient forward failure so the engine retries.</returns>
    public async Task<bool> DeliverAsync(StoreAndForwardMessage message)
    {
        // StoreAndForward-018: an unreadable payload cannot be fixed by retrying.
@@ -103,6 +103,7 @@ public class ReplicationService
    /// </summary>
    /// <param name="operation">The replication operation to apply.</param>
    /// <param name="storage">The standby node's store-and-forward storage to update.</param>
+    /// <returns>A task representing the asynchronous apply operation.</returns>
    public async Task ApplyReplicatedOperationAsync(
        ReplicationOperation operation,
        StoreAndForwardStorage storage)
@@ -11,6 +11,7 @@ public static class ServiceCollectionExtensions
    /// Registers Store-and-Forward services including storage, the delivery service, and the replication service.
    /// </summary>
    /// <param name="services">The service collection to register into.</param>
+    /// <returns>The same <paramref name="services"/> collection, for chaining.</returns>
    public static IServiceCollection AddStoreAndForward(this IServiceCollection services)
    {
        services.AddSingleton<StoreAndForwardStorage>(sp =>
@@ -71,6 +72,7 @@ public static class ServiceCollectionExtensions
    /// Registers Store-and-Forward Akka actor bindings. Actor creation is handled by the Host during actor system startup.
    /// </summary>
    /// <param name="services">The service collection to register into.</param>
+    /// <returns>The same <paramref name="services"/> collection, for chaining.</returns>
    public static IServiceCollection AddStoreAndForwardActors(this IServiceCollection services)
    {
        // Akka actor registration handled by Host component during actor system startup
@@ -210,6 +210,7 @@ public class StoreAndForwardService
    /// <summary>
    /// Initializes storage and starts the background retry timer.
    /// </summary>
+    /// <returns>A task representing the asynchronous start operation.</returns>
    public async Task StartAsync()
    {
        await _storage.InitializeAsync();
@@ -265,6 +266,7 @@ public class StoreAndForwardService
    /// (with a bounded <see cref="SweepShutdownWaitTimeout"/> so a hung
    /// dependency cannot block host shutdown indefinitely) before returning.
    /// </summary>
+    /// <returns>A task representing the asynchronous stop operation.</returns>
    public async Task StopAsync()
    {
        if (_retryTimer != null)
@@ -371,6 +373,7 @@ public class StoreAndForwardService
    /// non-routed run and for callers (notifications, pre-Task-6 callers) that
    /// do not supply one.
    /// </param>
+    /// <returns>A task that resolves to a result indicating whether the message was delivered or buffered.</returns>
    public async Task<StoreAndForwardResult> EnqueueAsync(
        StoreAndForwardCategory category,
        string target,
@@ -469,6 +472,7 @@ public class StoreAndForwardService
    /// <summary>
    /// WP-10: Background retry sweep. Processes all pending messages that are due for retry.
    /// </summary>
+    /// <returns>A task representing the asynchronous retry sweep.</returns>
    internal async Task RetryPendingMessagesAsync()
    {
        // Prevent overlapping retry sweeps
@@ -41,6 +41,7 @@ public class StoreAndForwardStorage
    /// <summary>
    /// Creates the sf_messages table if it does not exist.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task InitializeAsync()
    {
        EnsureDatabaseDirectoryExists();
@@ -145,6 +146,7 @@ public class StoreAndForwardStorage
    /// WP-9: Enqueues a new message with Pending status.
    /// </summary>
    /// <param name="message">The message to enqueue.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task EnqueueAsync(StoreAndForwardMessage message)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -190,6 +192,7 @@ public class StoreAndForwardStorage
    /// <summary>
    /// WP-10: Gets all messages that are due for retry (Pending status, last attempt older than retry interval).
    /// </summary>
+    /// <returns>A task that resolves to the list of messages due for retry, ordered by creation time ascending.</returns>
    public async Task<List<StoreAndForwardMessage>> GetMessagesForRetryAsync()
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -216,6 +219,7 @@ public class StoreAndForwardStorage
    /// WP-10: Updates a message after a delivery attempt.
    /// </summary>
    /// <param name="message">The message with updated retry count, status, and last error.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task UpdateMessageAsync(StoreAndForwardMessage message)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -255,6 +259,7 @@ public class StoreAndForwardStorage
    /// </summary>
    /// <param name="message">The message with the updated values to persist.</param>
    /// <param name="expectedStatus">The status the row must currently have for the update to proceed.</param>
+    /// <returns>A task that resolves to <c>true</c> if the row was updated; <c>false</c> if its status had already changed.</returns>
    public async Task<bool> UpdateMessageIfStatusAsync(
        StoreAndForwardMessage message,
        StoreAndForwardMessageStatus expectedStatus)
@@ -287,6 +292,7 @@ public class StoreAndForwardStorage
    /// WP-10: Removes a successfully delivered message.
    /// </summary>
    /// <param name="messageId">The id of the message to remove.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task RemoveMessageAsync(string messageId)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -311,6 +317,7 @@ public class StoreAndForwardStorage
    /// <param name="category">Optional category filter; null returns parked messages from all categories.</param>
    /// <param name="pageNumber">1-based page number.</param>
    /// <param name="pageSize">Maximum number of messages to return per page.</param>
+    /// <returns>A task that resolves to the page of parked messages and the total count of matching rows.</returns>
    public async Task<(List<StoreAndForwardMessage> Messages, int TotalCount)> GetParkedMessagesAsync(
        StoreAndForwardCategory? category = null,
        int pageNumber = 1,
@@ -366,6 +373,7 @@ public class StoreAndForwardStorage
    /// by accident, and a long interval would instead delay the operator's retry.
    /// </summary>
    /// <param name="messageId">The id of the parked message to move back to Pending.</param>
+    /// <returns>A task that resolves to <c>true</c> if the message was found and reset to Pending; <c>false</c> if not found or not in Parked status.</returns>
    public async Task<bool> RetryParkedMessageAsync(string messageId)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -389,6 +397,7 @@ public class StoreAndForwardStorage
    /// WP-12: Permanently discards a parked message.
    /// </summary>
    /// <param name="messageId">The id of the parked message to discard.</param>
+    /// <returns>A task that resolves to <c>true</c> if the message was found and deleted; <c>false</c> if not found or not in Parked status.</returns>
    public async Task<bool> DiscardParkedMessageAsync(string messageId)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -406,6 +415,7 @@ public class StoreAndForwardStorage
    /// <summary>
    /// WP-14: Gets buffer depth by category (count of pending messages per category).
    /// </summary>
+    /// <returns>A task that resolves to a dictionary mapping each category to its pending message count.</returns>
    public async Task<Dictionary<StoreAndForwardCategory, int>> GetBufferDepthByCategoryAsync()
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -436,6 +446,7 @@ public class StoreAndForwardStorage
    /// Returns the count of messages for a given origin instance.
    /// </summary>
    /// <param name="instanceName">The origin instance name to count messages for.</param>
+    /// <returns>A task that resolves to the number of messages whose origin instance matches <paramref name="instanceName"/>.</returns>
    public async Task<int> GetMessageCountByOriginInstanceAsync(string instanceName)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -455,6 +466,7 @@ public class StoreAndForwardStorage
    /// Gets a message by ID.
    /// </summary>
    /// <param name="messageId">The id of the message to retrieve.</param>
+    /// <returns>A task that resolves to the matching message, or <c>null</c> if not found.</returns>
    public async Task<StoreAndForwardMessage?> GetMessageByIdAsync(string messageId)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -476,6 +488,7 @@ public class StoreAndForwardStorage
    /// <summary>
    /// Gets the count of parked messages (for health reporting).
    /// </summary>
+    /// <returns>A task that resolves to the number of messages currently in Parked status.</returns>
    public async Task<int> GetParkedMessageCountAsync()
    {
        await using var conn = new SqliteConnection(_connectionString);
@@ -491,6 +504,7 @@ public class StoreAndForwardStorage
    /// Gets total message count by status.
    /// </summary>
    /// <param name="status">The status to filter by.</param>
+    /// <returns>A task that resolves to the count of messages with the specified status.</returns>
    public async Task<int> GetMessageCountByStatusAsync(StoreAndForwardMessageStatus status)
    {
        await using var connection = new SqliteConnection(_connectionString);