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.

src/ZB.MOM.WW.ScadaBridge.Commons/Types/Alarms/AlarmConditionStateFactory.cs

@@ -10,6 +10,9 @@ public static class AlarmConditionStateFactory
     /// auto-acked, never shelved or suppressed, not confirmable, and their
     /// severity is the configured priority. Active mirrors the alarm State.
     /// </summary>
+    /// <param name="state">The current alarm state used to derive the Active flag.</param>
+    /// <param name="priority">Configured priority mapped to the Severity field (0–1000).</param>
+    /// <returns>An <see cref="AlarmConditionState"/> reflecting the computed alarm's lifecycle (auto-acked, unshelved, not suppressed).</returns>
     public static AlarmConditionState ForComputed(AlarmState state, int priority) =>
         new(Active: state == AlarmState.Active, Acknowledged: true, Confirmed: null,
             Shelve: AlarmShelveState.Unshelved, Suppressed: false, Severity: priority);

src/ZB.MOM.WW.ScadaBridge.Commons/Types/Audit/AuditDetailsCodec.cs

@@ -46,6 +46,8 @@ public static class AuditDetailsCodec
     /// Serializes <paramref name="details"/> to a compact, deterministic JSON string
     /// suitable for storage in <c>AuditEvent.DetailsJson</c>.
     /// </summary>
+    /// <param name="details">The audit details instance to serialize.</param>
+    /// <returns>A compact, deterministic JSON string representing the audit details.</returns>
     public static string Serialize(AuditDetails details)
         => JsonSerializer.Serialize(details, Options);
 
@@ -54,6 +56,8 @@ public static class AuditDetailsCodec
     /// Returns an empty (all-null) <see cref="AuditDetails"/> when <paramref name="json"/>
     /// is <c>null</c>, empty, or whitespace — never throws.
     /// </summary>
+    /// <param name="json">The JSON string to deserialize; null or whitespace returns an empty instance.</param>
+    /// <returns>The deserialized <see cref="AuditDetails"/>, or an empty instance on null/invalid input.</returns>
     public static AuditDetails Deserialize(string? json)
     {
         if (string.IsNullOrWhiteSpace(json))

src/ZB.MOM.WW.ScadaBridge.Commons/Types/Audit/AuditFieldBuilders.cs

@@ -22,12 +22,17 @@ public static class AuditFieldBuilders
     /// <summary>
     /// Returns the canonical <c>Action</c> string: <c>"{channel}.{kind}"</c>.
     /// </summary>
+    /// <param name="channel">The audit channel (e.g. ExternalSystem, Notification).</param>
+    /// <param name="kind">The audit kind (e.g. Sync, Cached, InboundAuthFailure).</param>
+    /// <returns>A dot-separated string in the form <c>"{channel}.{kind}"</c>.</returns>
     public static string BuildAction(AuditChannel channel, AuditKind kind)
         => $"{channel}.{kind}";
 
     /// <summary>
     /// Returns the canonical <c>Category</c> string: the channel name.
     /// </summary>
+    /// <param name="channel">The audit channel whose name becomes the category.</param>
+    /// <returns>The channel enum name as a string (e.g. <c>"ApiOutbound"</c>).</returns>
     public static string BuildCategory(AuditChannel channel)
         => channel.ToString();
 }

src/ZB.MOM.WW.ScadaBridge.Commons/Types/Audit/AuditOutcomeProjector.cs

@@ -26,6 +26,9 @@ public static class AuditOutcomeProjector
     /// Projects <paramref name="status"/> + <paramref name="kind"/> onto the canonical
     /// <see cref="AuditOutcome"/>.
     /// </summary>
+    /// <param name="status">The audit status of the operation.</param>
+    /// <param name="kind">The audit kind; <see cref="AuditKind.InboundAuthFailure"/> takes precedence over status.</param>
+    /// <returns>The projected <see cref="AuditOutcome"/> value.</returns>
     public static AuditOutcome Project(AuditStatus status, AuditKind kind)
     {
         // Auth-failure kind takes absolute precedence — checked before any status rule.

src/ZB.MOM.WW.ScadaBridge.Commons/Types/Audit/AuditRowProjection.cs

@@ -64,6 +64,8 @@ public static class AuditRowProjection
     /// <see cref="ScadaBridgeAuditEventFactory"/>); a missing/unparseable discriminator
     /// falls back to the first enum member (defensive — production rows always carry them).
     /// </summary>
+    /// <param name="evt">The canonical audit event to decompose.</param>
+    /// <returns>An <see cref="AuditRowValues"/> struct containing the typed column values extracted from the event.</returns>
     public static AuditRowValues Decompose(AuditEvent evt)
     {
         ArgumentNullException.ThrowIfNull(evt);
@@ -115,6 +117,8 @@ public static class AuditRowProjection
     /// are rebuilt via the field builders / outcome projector, and every domain field is
     /// re-serialized into <c>DetailsJson</c> via <see cref="AuditDetailsCodec"/>.
     /// </summary>
+    /// <param name="v">The typed column values to recompose into a canonical event.</param>
+    /// <returns>A reconstructed canonical <see cref="AuditEvent"/> with domain fields re-serialized into <c>DetailsJson</c>.</returns>
     public static AuditEvent Recompose(in AuditRowValues v)
     {
         var details = new AuditDetails
@@ -163,6 +167,9 @@ public static class AuditRowProjection
     /// record, so the central ingest paths stamp it here rather than on a top-level
     /// property as the legacy bespoke record allowed.
     /// </summary>
+    /// <param name="evt">The canonical audit event to update.</param>
+    /// <param name="ingestedAtUtc">The central-side ingest timestamp to stamp into the event.</param>
+    /// <returns>A new <see cref="AuditEvent"/> with <c>IngestedAtUtc</c> set inside <c>DetailsJson</c>.</returns>
     public static AuditEvent WithIngestedAtUtc(AuditEvent evt, DateTimeOffset ingestedAtUtc)
     {
         ArgumentNullException.ThrowIfNull(evt);
@@ -179,6 +186,10 @@ public static class AuditRowProjection
     /// or does not match any declared member name — so callers never throw on an
     /// unknown/renamed enum string (legacy or corrupt rows degrade gracefully).
     /// </summary>
+    /// <typeparam name="TEnum">The enum type to parse into.</typeparam>
+    /// <param name="value">The string to parse; null or empty triggers the fallback.</param>
+    /// <param name="fallback">Value returned when <paramref name="value"/> is null, empty, or unrecognised.</param>
+    /// <returns>The parsed <typeparamref name="TEnum"/> value, or <paramref name="fallback"/> when the input is null, empty, or unrecognised.</returns>
     public static TEnum ParseEnum<TEnum>(string? value, TEnum fallback) where TEnum : struct, Enum
         => !string.IsNullOrEmpty(value) && Enum.TryParse<TEnum>(value, ignoreCase: false, out var parsed)
             ? parsed
@@ -194,6 +205,8 @@ public static class AuditRowProjection
 public static class AuditEventRowExtensions
 {
     /// <summary>Decomposes this canonical record into its typed 24-field view.</summary>
+    /// <param name="evt">The canonical audit event to decompose.</param>
+    /// <returns>An <see cref="AuditRowProjection.AuditRowValues"/> struct with all domain fields extracted from the event.</returns>
     public static AuditRowProjection.AuditRowValues AsRow(this AuditEvent evt)
         => AuditRowProjection.Decompose(evt);
 }

src/ZB.MOM.WW.ScadaBridge.Commons/Types/Audit/ScadaBridgeAuditEventFactory.cs

@@ -59,6 +59,7 @@ public static class ScadaBridgeAuditEventFactory
     /// <param name="payloadTruncated">True when summaries were truncated to the payload cap (DetailsJson).</param>
     /// <param name="extra">Free-form JSON extension for channel-specific extras (DetailsJson).</param>
     /// <param name="ingestedAtUtc">UTC ingest timestamp (central-set; DetailsJson).</param>
+    /// <returns>A fully-populated <see cref="AuditEvent"/> with the top-level fields and serialized <c>DetailsJson</c> set.</returns>
     public static AuditEvent Create(
         AuditChannel channel,
         AuditKind kind,

src/ZB.MOM.WW.ScadaBridge.Commons/Types/Flattening/ValidationResult.cs

@@ -13,15 +13,18 @@ public sealed record ValidationResult
     public IReadOnlyList<ValidationEntry> Warnings { get; init; } = [];
 
     /// <summary>Returns a result with no errors or warnings.</summary>
+    /// <returns>A <see cref="ValidationResult"/> with empty error and warning lists.</returns>
     public static ValidationResult Success() => new();
 
     /// <summary>Returns a result containing the given errors.</summary>
     /// <param name="errors">The validation errors to include.</param>
+    /// <returns>A <see cref="ValidationResult"/> whose <see cref="Errors"/> list contains the supplied entries.</returns>
     public static ValidationResult FromErrors(params ValidationEntry[] errors) =>
         new() { Errors = errors };
 
     /// <summary>Merges multiple validation results into a single combined result.</summary>
     /// <param name="results">The results to merge.</param>
+    /// <returns>A new <see cref="ValidationResult"/> with all errors and warnings from every supplied result combined.</returns>
     public static ValidationResult Merge(params ValidationResult[] results)
     {
         var errors = new List<ValidationEntry>();
@@ -54,6 +57,7 @@ public sealed record ValidationEntry
     /// <param name="category">The validation category.</param>
     /// <param name="message">The error message.</param>
     /// <param name="entityName">The canonical name of the entity that caused the error, if any.</param>
+    /// <returns>A new <see cref="ValidationEntry"/> representing an error.</returns>
     public static ValidationEntry Error(ValidationCategory category, string message, string? entityName = null) =>
         new() { Category = category, Message = message, EntityName = entityName };
 
@@ -61,6 +65,7 @@ public sealed record ValidationEntry
     /// <param name="category">The validation category.</param>
     /// <param name="message">The warning message.</param>
     /// <param name="entityName">The canonical name of the entity that triggered the warning, if any.</param>
+    /// <returns>A new <see cref="ValidationEntry"/> representing a warning.</returns>
     public static ValidationEntry Warning(ValidationCategory category, string message, string? entityName = null) =>
         new() { Category = category, Message = message, EntityName = entityName };
 }

src/ZB.MOM.WW.ScadaBridge.Commons/Types/Result.cs

@@ -49,6 +49,7 @@ public sealed class Result<T>
     /// <param name="error">Non-blank error message describing the failure.</param>
     /// <exception cref="ArgumentNullException"><paramref name="error"/> is null.</exception>
     /// <exception cref="ArgumentException"><paramref name="error"/> is empty or whitespace.</exception>
+    /// <returns>A failed <see cref="Result{T}"/> carrying the error message.</returns>
     public static Result<T> Failure(string error) => new(error);
 
     /// <summary>Pattern-matches the result, invoking either the success or failure delegate.</summary>

src/ZB.MOM.WW.ScadaBridge.Commons/Types/TrackedOperationId.cs

@@ -22,6 +22,7 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Types;
 public readonly record struct TrackedOperationId(Guid Value)
 {
     /// <summary>Mint a fresh id at the call site (script-thread safe).</summary>
+    /// <returns>A new <see cref="TrackedOperationId"/> wrapping a freshly generated GUID.</returns>
     public static TrackedOperationId New() => new(Guid.NewGuid());
 
     /// <summary>
@@ -30,6 +31,7 @@ public readonly record struct TrackedOperationId(Guid Value)
     /// <see cref="TryParse"/> instead.
     /// </summary>
     /// <param name="s">GUID string to parse.</param>
+    /// <returns>A <see cref="TrackedOperationId"/> wrapping the parsed GUID.</returns>
     public static TrackedOperationId Parse(string s) => new(Guid.Parse(s));
 
     /// <summary>
@@ -39,6 +41,7 @@ public readonly record struct TrackedOperationId(Guid Value)
     /// </summary>
     /// <param name="s">GUID string to parse, or null.</param>
     /// <param name="result">Parsed value on success; default on failure.</param>
+    /// <returns><c>true</c> if the string was successfully parsed; otherwise <c>false</c>.</returns>
     public static bool TryParse(string? s, out TrackedOperationId result)
     {
         if (Guid.TryParse(s, out var g))

src/ZB.MOM.WW.ScadaBridge.Commons/Types/ValueFormatter.cs

@@ -14,6 +14,7 @@ public static class ValueFormatter
     /// scalars and comma-separated elements for array/collection types.
     /// </summary>
     /// <param name="value">The value to format; null returns an empty string.</param>
+    /// <returns>The culture-invariant string representation of the value, or an empty string if <paramref name="value"/> is <c>null</c>.</returns>
     /// <remarks>
     /// Formatting is <see cref="CultureInfo.InvariantCulture">culture-invariant</see>:
     /// numbers and <see cref="DateTime"/> values render the same regardless of the