docs(src): fix CommentChecker findings across src/ — 1,032 → 5 (all false positives)
Comment/XML-doc changes only, no code logic: - strip project-tracking references (WP*, P*-*, row-NN, #NN, Task N) from comments, keeping the explanatory rationale - add missing summaries, <param>, <returns>, <typeparam> and <inheritdoc/> - replace misused <inheritdoc/> with real docs; where <inheritdoc/> was combined with useful remarks, move the rationale into // comments - drop stale replicationActor <param> on DeploymentManagerActor ctor Remaining 5 are false positives (CWE-1236 x2, failures-1, year-0001, M365). Build 0 errors / 0 warnings.
This commit is contained in:
Joseph Doherty
@@ -105,11 +105,11 @@ public class InstanceActor : ReceiveActor
|
||||
// deserialized configuration (last-wins on duplicate canonical names,
|
||||
// mirroring the rest of the actor's by-name dictionaries). Each entry
|
||||
// additionally carries its DataType/ElementDataType parsed ONCE at
|
||||
// config-apply time (perf remediation, arch-review WP1.5) so the hot
|
||||
// config-apply time so the hot
|
||||
// TagValueUpdate path never re-Enum.TryParse's a string per update.
|
||||
private readonly Dictionary<string, AttributeIndexEntry> _resolvedAttributeByName = new();
|
||||
|
||||
// Static-override write coalescing (perf remediation, arch-review WP1.5):
|
||||
// Static-override write coalescing:
|
||||
// mirrors NativeAlarmActor's MarkDirtyUpsert/FlushDirtyUpserts (P4) shape.
|
||||
// A burst of rapid SetAttribute calls on the same or different attributes
|
||||
// collapses into one batched SQLite transaction on a short single-shot
|
||||
@@ -124,7 +124,7 @@ public class InstanceActor : ReceiveActor
|
||||
/// <summary>
|
||||
/// The deploy path's static-override / native-alarm reset, supplied by
|
||||
/// <see cref="DeploymentManagerActor.CreateInstanceActor"/> on a (re)deploy and
|
||||
/// <see langword="null"/> on every other start (arch-review 2026-08-19 P1-2). When set,
|
||||
/// <see langword="null"/> on every other start When set,
|
||||
/// <see cref="PreStart"/> starts the override load only once it has completed, so a
|
||||
/// redeploy can never load the PREDECESSOR's overrides into the successor's memory.
|
||||
/// </summary>
|
||||
@@ -135,8 +135,7 @@ public class InstanceActor : ReceiveActor
|
||||
internal sealed record StaticOverridesFlushed(IActorRef Actor, Exception? Error);
|
||||
|
||||
/// <summary>
|
||||
/// Cached string forms of <see cref="QualityCode"/> (perf remediation, arch-review
|
||||
/// WP1.5) — the TagValueUpdate ingest path calls this once or twice per update, so a
|
||||
/// Cached string forms of <see cref="QualityCode"/> — the TagValueUpdate ingest path calls this once or twice per update, so a
|
||||
/// static lookup replaces repeated <see cref="Enum.ToString()"/> reflection.
|
||||
/// </summary>
|
||||
private static readonly Dictionary<QualityCode, string> QualityStrings = new()
|
||||
@@ -150,7 +149,7 @@ public class InstanceActor : ReceiveActor
|
||||
QualityStrings.TryGetValue(quality, out var s) ? s : quality.ToString();
|
||||
|
||||
/// <summary>
|
||||
/// O(1) attribute-resolution index entry (perf remediation, arch-review WP1.5): wraps a
|
||||
/// O(1) attribute-resolution index entry: wraps a
|
||||
/// <see cref="ResolvedAttribute"/> together with its <see cref="DataType"/> /
|
||||
/// element <see cref="DataType"/> / IsList classification, parsed ONCE when the entry
|
||||
/// is built (constructor) instead of re-parsed via <see cref="Enum.TryParse{DataType}"/>
|
||||
@@ -280,7 +279,7 @@ public class InstanceActor : ReceiveActor
|
||||
{
|
||||
// Parse DataType/ElementDataType ONCE here (config-apply time) and index
|
||||
// the wrapping entry for O(1) lookup on the hot TagValueUpdate ingest path
|
||||
// (last-wins on duplicate names) — perf remediation, arch-review WP1.5.
|
||||
// (last-wins on duplicate names)
|
||||
var dataType = ParseDataType(attr.DataType);
|
||||
var elementDataType = ParseElementDataType(attr.ElementDataType);
|
||||
var isList = dataType == DataType.List;
|
||||
@@ -398,8 +397,7 @@ public class InstanceActor : ReceiveActor
|
||||
|
||||
// Asynchronously load static overrides from SQLite and pipe to self. On a (re)deploy
|
||||
// the read is chained behind the reset the Deployment Manager dispatched before this
|
||||
// actor existed, so it can only ever observe the CLEARED table (arch-review
|
||||
// 2026-08-19 P1-2). A faulted reset does not block the load — the deploy itself fails
|
||||
// actor existed, so it can only ever observe the CLEARED table. A faulted reset does not block the load — the deploy itself fails
|
||||
// on that fault through the persistence join, which stops this actor anyway.
|
||||
var self = Self;
|
||||
var instanceName = _instanceUniqueName;
|
||||
@@ -519,7 +517,7 @@ public class InstanceActor : ReceiveActor
|
||||
private void HandleSetStaticAttribute(SetStaticAttributeCommand command)
|
||||
{
|
||||
// O(1) lookup via the existing hot-path index instead of a linear scan over
|
||||
// _configuration.Attributes (perf remediation, arch-review WP1.5).
|
||||
// _configuration.Attributes.
|
||||
_resolvedAttributeByName.TryGetValue(command.AttributeName, out var resolved);
|
||||
|
||||
// Reject writes targeting an attribute that does not exist
|
||||
@@ -640,7 +638,7 @@ public class InstanceActor : ReceiveActor
|
||||
|
||||
/// <summary>
|
||||
/// Records the latest value per attribute name and arms the coalesced flush timer
|
||||
/// (perf remediation, arch-review WP1.5) — mirrors NativeAlarmActor's
|
||||
/// — mirrors NativeAlarmActor's
|
||||
/// MarkDirtyUpsert/FlushDirtyUpserts (P4) shape. A burst of rapid static writes
|
||||
/// collapses into one batched SQLite transaction instead of a write per call.
|
||||
/// </summary>
|
||||
@@ -1157,7 +1155,7 @@ public class InstanceActor : ReceiveActor
|
||||
/// actor.
|
||||
///
|
||||
/// Takes the already-parsed <paramref name="dataType"/>/<paramref name="elementType"/>
|
||||
/// (perf remediation, arch-review WP1.5) rather than re-parsing from the attribute's
|
||||
/// rather than re-parsing from the attribute's
|
||||
/// raw DataType strings — every call site now resolves these once via
|
||||
/// <see cref="AttributeIndexEntry"/> at config-apply time.
|
||||
/// </summary>
|
||||
@@ -1185,8 +1183,7 @@ public class InstanceActor : ReceiveActor
|
||||
/// non-enumerable value, or any element that cannot be coerced — the caller then
|
||||
/// marks the attribute quality Bad. Never throws.
|
||||
///
|
||||
/// Takes the already-parsed <paramref name="elementType"/> (perf remediation,
|
||||
/// arch-review WP1.5) — see <see cref="DecodeAttributeValue"/>.
|
||||
/// Takes the already-parsed <paramref name="elementType"/> — see <see cref="DecodeAttributeValue"/>.
|
||||
/// </summary>
|
||||
private bool TryCoerceListValue(DataType? elementType, object? incoming, out object? typedList)
|
||||
{
|
||||
@@ -1325,13 +1322,18 @@ public class InstanceActor : ReceiveActor
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Pure backoff step for the tag-subscribe retry (Lever 1, 2026-08-28): double the
|
||||
/// Pure backoff step for the tag-subscribe retry: double the
|
||||
/// interval just used, apply ±20 % jitter from <paramref name="jitterUnit"/> (a
|
||||
/// uniform sample in [0,1]; 0.5 = no jitter) so N instances on one connection do not
|
||||
/// re-storm in lockstep, then clamp to [floor, ceiling]. A ceiling below the floor
|
||||
/// degrades to a fixed floor interval rather than shrinking below it — same contract
|
||||
/// as <c>DataConnectionActor.NextTagResolutionInterval</c>.
|
||||
/// </summary>
|
||||
/// <param name="current">The interval just used.</param>
|
||||
/// <param name="floor">The minimum interval.</param>
|
||||
/// <param name="max">The maximum interval; a value below <paramref name="floor"/> degrades to the floor.</param>
|
||||
/// <param name="jitterUnit">A uniform sample in [0,1] used to apply jitter; 0.5 means no jitter.</param>
|
||||
/// <returns>The next retry interval, clamped to the allowed range.</returns>
|
||||
internal static TimeSpan NextTagSubscribeInterval(TimeSpan current, TimeSpan floor, TimeSpan max, double jitterUnit)
|
||||
{
|
||||
var ceiling = max < floor ? floor : max;
|
||||
@@ -1658,7 +1660,7 @@ public class InstanceActor : ReceiveActor
|
||||
{
|
||||
var now = DateTimeOffset.UtcNow;
|
||||
|
||||
// Alarms-only projection (WP2.3): the central live-alarm cache seeds/reconciles
|
||||
// Alarms-only projection: the central live-alarm cache seeds/reconciles
|
||||
// through this same query surface and throws every attribute row away. Building
|
||||
// and shipping them is pure waste — one instance with a few hundred attributes
|
||||
// costs more on the wire than the whole alarm set of the site. The flag is
|
||||
@@ -2153,7 +2155,7 @@ public class InstanceActor : ReceiveActor
|
||||
/// <param name="SourceExecutionId">Execution id of the writer that took the arm.</param>
|
||||
private sealed record DisarmTrace(string AttributeName, Guid SourceExecutionId);
|
||||
|
||||
/// <summary>Self-tell that fires the coalesced static-override persist flush (P4, arch-review WP1.5).</summary>
|
||||
/// <summary>Self-tell that fires the coalesced static-override persist flush.</summary>
|
||||
private sealed class FlushStaticOverrides
|
||||
{
|
||||
public static readonly FlushStaticOverrides Instance = new();
|
||||
|
||||
Reference in New Issue
Block a user