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.
This commit is contained in:
Joseph Doherty
2026-06-03 11:39:32 -04:00
parent a050170414
commit eabf270d71
208 changed files with 867 additions and 114 deletions
@@ -182,6 +182,7 @@ public partial class TransportExport : ComponentBase
/// importer enforces its own strength + lockout policies.
/// </summary>
/// <param name="s">The passphrase string to score.</param>
/// <returns>An integer from 0 (blank) to 4 (long, mixed case, digits, and symbols).</returns>
internal static int PassphraseStrength(string s)
{
if (string.IsNullOrEmpty(s)) return 0;
@@ -261,6 +262,7 @@ public partial class TransportExport : ComponentBase
/// knows exactly what an unencrypted export would leak.
/// </summary>
/// <param name="resolved">The resolved export closure whose secret fields are counted.</param>
/// <returns>The total number of non-empty secret fields across all external systems, SMTP configs, and database connections.</returns>
internal static int CountSecrets(ResolvedExport resolved)
{
var count = 0;
@@ -367,6 +369,7 @@ public partial class TransportExport : ComponentBase
/// </summary>
/// <param name="sourceEnvironment">The environment label to embed in the filename (sanitised to filename-safe characters).</param>
/// <param name="nowUtc">Timestamp to use for the datetime segment; defaults to <see cref="DateTimeOffset.UtcNow"/> when null.</param>
/// <returns>A filename of the form <c>scadabundle-{env}-{yyyy-MM-dd-HHmmss}.scadabundle</c>.</returns>
internal static string BuildFilename(string sourceEnvironment, DateTimeOffset? nowUtc = null)
{
var safe = SanitizeForFilename(sourceEnvironment);
@@ -427,6 +430,7 @@ public partial class TransportExport : ComponentBase
/// <param name="all">The full resolved list including both seed and auto-included items.</param>
/// <param name="seed">The set of explicitly selected item ids.</param>
/// <param name="idOf">Function that extracts the integer id from an item.</param>
/// <returns>Items from <paramref name="all"/> whose ids are not in <paramref name="seed"/> (auto-included dependencies).</returns>
internal static IReadOnlyList<T> AutoIncluded<T>(IReadOnlyList<T> all, IReadOnlyCollection<int> seed, Func<T, int> idOf)
{
return all.Where(x => !seed.Contains(idOf(x))).ToList();