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
@@ -23,6 +23,7 @@ public class SiteStorageInitializer : IHostedService
    /// Initializes the SQLite schema before the actor system starts.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token for the startup operation.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task StartAsync(CancellationToken cancellationToken)
    {
        await _storage.InitializeAsync();
@@ -32,5 +33,6 @@ public class SiteStorageInitializer : IHostedService
    /// No-op stop; schema initialization does not require cleanup.
    /// </summary>
    /// <param name="cancellationToken">Unused cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
 }
@@ -30,12 +30,14 @@ public class SiteStorageService
    /// reaching into private state via reflection (SiteRuntime-006). The caller owns
    /// the connection and is responsible for opening and disposing it.
    /// </summary>
+    /// <returns>A new, unopened <see cref="SqliteConnection"/> against the site database.</returns>
    public SqliteConnection CreateConnection() => new(_connectionString);

    /// <summary>
    /// Creates the SQLite tables if they do not exist.
    /// Called once on site startup.
    /// </summary>
+    /// <returns>A task that completes when all tables have been created or verified.</returns>
    public async Task InitializeAsync()
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -157,6 +159,7 @@ public class SiteStorageService
    /// <summary>
    /// Returns all deployed instance configurations from SQLite.
    /// </summary>
+    /// <returns>A task that resolves to the list of all deployed instance configurations.</returns>
    public async Task<List<DeployedInstance>> GetAllDeployedConfigsAsync()
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -193,6 +196,7 @@ public class SiteStorageService
    /// <param name="deploymentId">The unique deployment identifier.</param>
    /// <param name="revisionHash">The configuration revision hash for staleness detection.</param>
    /// <param name="isEnabled">Whether the instance is enabled.</param>
+    /// <returns>A task that completes when the configuration has been stored or updated.</returns>
    public async Task StoreDeployedConfigAsync(
        string instanceName,
        string configJson,
@@ -229,6 +233,7 @@ public class SiteStorageService
    /// Removes a deployed instance configuration and its static overrides.
    /// </summary>
    /// <param name="instanceName">The unique name of the instance to remove.</param>
+    /// <returns>A task that completes when the configuration and its overrides have been removed.</returns>
    public async Task RemoveDeployedConfigAsync(string instanceName)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -269,6 +274,7 @@ public class SiteStorageService
    /// </summary>
    /// <param name="instanceName">The unique name of the instance.</param>
    /// <param name="isEnabled">Whether the instance should be enabled.</param>
+    /// <returns>A task that completes when the enabled flag has been updated.</returns>
    public async Task SetInstanceEnabledAsync(string instanceName, bool isEnabled)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -296,6 +302,7 @@ public class SiteStorageService
    /// Returns all static attribute overrides for an instance.
    /// </summary>
    /// <param name="instanceName">The unique name of the instance.</param>
+    /// <returns>A task that resolves to a dictionary mapping attribute names to their override values.</returns>
    public async Task<Dictionary<string, string>> GetStaticOverridesAsync(string instanceName)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -324,6 +331,7 @@ public class SiteStorageService
    /// <param name="instanceName">The unique name of the instance.</param>
    /// <param name="attributeName">The name of the attribute to override.</param>
    /// <param name="value">The override value for the attribute.</param>
+    /// <returns>A task that completes when the override has been saved.</returns>
    public async Task SetStaticOverrideAsync(string instanceName, string attributeName, string value)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -350,6 +358,7 @@ public class SiteStorageService
    /// Called on redeployment to reset overrides.
    /// </summary>
    /// <param name="instanceName">The unique name of the instance.</param>
+    /// <returns>A task that completes when all overrides for the instance have been deleted.</returns>
    public async Task ClearStaticOverridesAsync(string instanceName)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -369,6 +378,12 @@ public class SiteStorageService
    /// Inserts or updates a single mirrored native alarm condition, keyed by
    /// (instance, source canonical name, source reference). Newer transitions overwrite older ones.
    /// </summary>
+    /// <param name="instanceName">Unique name of the instance owning the alarm.</param>
+    /// <param name="sourceCanonicalName">Canonical name of the source binding (connection/alarm source).</param>
+    /// <param name="sourceReference">Source-system reference key identifying the specific alarm condition.</param>
+    /// <param name="conditionJson">Serialized <see cref="AlarmConditionState"/> JSON snapshot.</param>
+    /// <param name="lastTransitionAt">Timestamp of the most recent condition transition.</param>
+    /// <returns>A task that completes when the alarm condition has been inserted or updated.</returns>
    public async Task UpsertNativeAlarmAsync(
        string instanceName, string sourceCanonicalName, string sourceReference,
        string conditionJson, DateTimeOffset lastTransitionAt)
@@ -397,6 +412,10 @@ public class SiteStorageService
    /// <summary>
    /// Removes a single mirrored native alarm condition (e.g. a return-to-normal that drops out of retention).
    /// </summary>
+    /// <param name="instanceName">Unique name of the instance owning the alarm.</param>
+    /// <param name="sourceCanonicalName">Canonical name of the source binding.</param>
+    /// <param name="sourceReference">Source-system reference key identifying the alarm condition to remove.</param>
+    /// <returns>A task that completes when the alarm condition row has been deleted.</returns>
    public async Task DeleteNativeAlarmAsync(string instanceName, string sourceCanonicalName, string sourceReference)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -419,6 +438,9 @@ public class SiteStorageService
    /// Returns all mirrored native alarm conditions for an instance's source binding,
    /// used to rehydrate a NativeAlarmActor on (re)start.
    /// </summary>
+    /// <param name="instanceName">Unique name of the instance to query.</param>
+    /// <param name="sourceCanonicalName">Canonical name of the source binding to query.</param>
+    /// <returns>A task that resolves to the list of stored native alarm condition rows for the binding.</returns>
    public async Task<IReadOnlyList<NativeAlarmRow>> GetNativeAlarmsAsync(string instanceName, string sourceCanonicalName)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -448,6 +470,8 @@ public class SiteStorageService
    /// <summary>
    /// Clears all mirrored native alarm conditions for an instance. Called on redeployment / stop.
    /// </summary>
+    /// <param name="instanceName">Unique name of the instance whose native alarm state should be cleared.</param>
+    /// <returns>A task that completes when all native alarm rows for the instance have been deleted.</returns>
    public async Task ClearNativeAlarmsForInstanceAsync(string instanceName)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -470,6 +494,7 @@ public class SiteStorageService
    /// <param name="code">The script code.</param>
    /// <param name="parameterDefs">JSON representation of parameter definitions, if any.</param>
    /// <param name="returnDef">JSON representation of the return type definition, if any.</param>
+    /// <returns>A task that completes when the shared script has been stored or updated.</returns>
    public async Task StoreSharedScriptAsync(string name, string code, string? parameterDefs, string? returnDef)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -498,6 +523,7 @@ public class SiteStorageService
    /// <summary>
    /// Returns all stored shared scripts.
    /// </summary>
+    /// <returns>A task that resolves to the list of all stored shared scripts.</returns>
    public async Task<List<StoredSharedScript>> GetAllSharedScriptsAsync()
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -532,6 +558,7 @@ public class SiteStorageService
    /// <param name="authType">The authentication type (e.g., 'ApiKey', 'BasicAuth').</param>
    /// <param name="authConfig">Authentication configuration JSON, if applicable.</param>
    /// <param name="methodDefs">JSON representation of available method definitions, if any.</param>
+    /// <returns>A task that completes when the external system definition has been stored or updated.</returns>
    public async Task StoreExternalSystemAsync(
        string name, string endpointUrl, string authType, string? authConfig, string? methodDefs)
    {
@@ -568,6 +595,7 @@ public class SiteStorageService
    /// <param name="connectionString">The database connection string.</param>
    /// <param name="maxRetries">Maximum number of retry attempts.</param>
    /// <param name="retryDelay">Delay between retry attempts.</param>
+    /// <returns>A task that completes when the database connection definition has been stored or updated.</returns>
    public async Task StoreDatabaseConnectionAsync(
        string name, string connectionString, int maxRetries, TimeSpan retryDelay)
    {
@@ -600,6 +628,7 @@ public class SiteStorageService
    /// </summary>
    /// <param name="name">The name of the notification list.</param>
    /// <param name="recipientEmails">List of recipient email addresses.</param>
+    /// <returns>A task that completes when the notification list has been stored or updated.</returns>
    public async Task StoreNotificationListAsync(string name, IReadOnlyList<string> recipientEmails)
    {
        await using var connection = new SqliteConnection(_connectionString);
@@ -633,6 +662,7 @@ public class SiteStorageService
    /// <param name="username">Username for authentication, if applicable.</param>
    /// <param name="password">Password for authentication, if applicable.</param>
    /// <param name="oauthConfig">OAuth2 configuration JSON, if applicable.</param>
+    /// <returns>A task that completes when the SMTP configuration has been stored or updated.</returns>
    public async Task StoreSmtpConfigurationAsync(
        string name, string server, int port, string authMode, string fromAddress,
        string? username, string? password, string? oauthConfig)
@@ -677,6 +707,7 @@ public class SiteStorageService
    /// <param name="configJson">Primary configuration as JSON.</param>
    /// <param name="backupConfigJson">Backup configuration as JSON, if applicable.</param>
    /// <param name="failoverRetryCount">Number of retries for failover attempts.</param>
+    /// <returns>A task that completes when the data connection definition has been stored or updated.</returns>
    public async Task StoreDataConnectionDefinitionAsync(
        string name, string protocol, string? configJson, string? backupConfigJson = null, int failoverRetryCount = 3)
    {
@@ -708,6 +739,7 @@ public class SiteStorageService
    /// <summary>
    /// Returns all stored data connection definitions.
    /// </summary>
+    /// <returns>A task that resolves to the list of all stored data connection definitions.</returns>
    public async Task<List<StoredDataConnectionDefinition>> GetAllDataConnectionDefinitionsAsync()
    {
        await using var connection = new SqliteConnection(_connectionString);