docs(xml): fill missing XML doc comments + strip task-tracking refs across src (fixdocs)

Add missing <summary>/<param>/<returns>/<typeparam> tags and switch
interface implementations to <inheritdoc/> across 106 files; strip
project bookkeeping identifiers (Task NN, #05-TNN, PLAN-04, StoreAndForward-0NN)
from shipped code comments while preserving the descriptive rationale.
Comment-only: zero code-logic lines changed; solution builds 0/0.

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj
This commit is contained in:
Joseph Doherty
2026-07-10 08:23:56 -04:00
parent 75007b9edd
commit 5a878b78d4
106 changed files with 580 additions and 180 deletions
@@ -80,14 +80,6 @@ public sealed class BundleSerializer
// count but rebuild ContentHash + Encryption fields against the bytes we
// actually write. The non-encryption manifest fields (source env, exported
// by, summary, contents, version) are preserved verbatim.
//
// T-005: bind the manifest's non-derivative fields into the AES-GCM AAD
// so a tampered SourceEnvironment / ExportedBy / etc. on a stolen bundle
// yields an authentication-tag mismatch on decrypt instead of a forged
// origin label slipping past the Step-4 confirmation gate. AAD is
// computed over a manifest normalised to empty ContentHash + null
// Encryption (those fields are derivative of the ciphertext / IV and
// cannot themselves be authenticated).
var aad = BundleManifestAad.Compute(manifest);
var (cipher, freshMeta) = encryptor.Encrypt(
contentBytes, passphrase, manifest.Encryption.Iterations, aad);
@@ -31,8 +31,19 @@ public sealed record EntityAggregate(
// Site/instance-scoped entities. Init-only with empty-array defaults so
// existing positional `new EntityAggregate(...)` callers keep compiling and
// never see a null collection; new callers opt in via object-initializer.
/// <summary>
/// The sites carried in this aggregate.
/// </summary>
public IReadOnlyList<Site> Sites { get; init; } = Array.Empty<Site>();
/// <summary>
/// The site-scoped data connections carried in this aggregate.
/// </summary>
public IReadOnlyList<DataConnection> DataConnections { get; init; } = Array.Empty<DataConnection>();
/// <summary>
/// The instances carried in this aggregate.
/// </summary>
public IReadOnlyList<Instance> Instances { get; init; } = Array.Empty<Instance>();
// SMS: carried alongside SmtpConfigurations. Init-only with an empty
@@ -40,6 +51,9 @@ public sealed record EntityAggregate(
// every existing positional `new EntityAggregate(...)` caller keeps compiling
// and never sees null; producers that resolve SMS config opt in via
// object-initializer.
/// <summary>
/// The SMS provider configurations carried in this aggregate.
/// </summary>
public IReadOnlyList<SmsConfiguration> SmsConfigurations { get; init; } = Array.Empty<SmsConfiguration>();
// Area id → name lookup for the exported instances. Areas are not carried as a
@@ -48,6 +62,9 @@ public sealed record EntityAggregate(
// a portable name at serialization time. Init-only with an empty default: producers
// that export instances populate it; every other caller keeps compiling and the
// serializer emits AreaName: null when an instance's AreaId isn't in the map.
/// <summary>
/// Lookup from area ID to area name for the exported instances' <c>AreaId</c> FKs.
/// </summary>
public IReadOnlyDictionary<int, string> AreaNameById { get; init; } =
new Dictionary<int, string>();
}
@@ -90,8 +107,19 @@ public sealed record BundleContentDto(
// object-initializer (`new BundleContentDto(...) { Sites = ... }`).
// These are written by the serializer (WhenWritingNull does not apply — they
// are non-null), so new bundles always carry the three arrays explicitly.
/// <summary>
/// The sites carried in this bundle payload.
/// </summary>
public IReadOnlyList<SiteDto> Sites { get; init; } = Array.Empty<SiteDto>();
/// <summary>
/// The site-scoped data connections carried in this bundle payload.
/// </summary>
public IReadOnlyList<DataConnectionDto> DataConnections { get; init; } = Array.Empty<DataConnectionDto>();
/// <summary>
/// The instances carried in this bundle payload.
/// </summary>
public IReadOnlyList<InstanceDto> Instances { get; init; } = Array.Empty<InstanceDto>();
// SMS: central-only SMS provider configs, carried alongside SmtpConfigs.
@@ -103,6 +131,9 @@ public sealed record BundleContentDto(
// 2. Source-compat: every existing positional `new BundleContentDto(...)` caller
// keeps compiling; producers that pack SMS configs opt in via the
// object-initializer.
/// <summary>
/// The SMS provider configurations carried in this bundle payload.
/// </summary>
public IReadOnlyList<SmsConfigDto> SmsConfigs { get; init; } = Array.Empty<SmsConfigDto>();
}
@@ -140,6 +171,9 @@ public sealed record TemplateDto(
// keeps compiling; producers opt in via the object-initializer.
// IsInherited placeholder rows ARE carried (the collision detector depends
// on them), mirroring how the flattener treats inherited native sources.
/// <summary>
/// The template-defined native alarm source bindings carried for this template.
/// </summary>
public IReadOnlyList<TemplateNativeAlarmSourceDto> NativeAlarmSources { get; init; } =
Array.Empty<TemplateNativeAlarmSourceDto>();
}
@@ -32,6 +32,7 @@ internal static class ImportValueNormalizer
/// <param name="elementType">The List element type (null for scalars).</param>
/// <param name="logger">Optional logger; a warning is emitted when a malformed value is left as-is.</param>
/// <param name="attributeName">Optional attribute name for the diagnostic message.</param>
/// <returns>The native-typed JSON form of the value, or the value unchanged when not applicable.</returns>
public static string? NormalizeListValue(
string? value,
DataType dataType,