dohertj2/lmxopcua
1
0
Fork 0
Code Issues 2 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: complete XML doc comments via fixdocs (2757 to 131 findings)

Browse Source 
Add missing <returns>/<param>/<summary>/<typeparam> tags and clean up
misused inheritdoc across 481 files so the documented API surface is
complete. Documentation-only (zero code lines changed). The 131 remaining
findings are inheritdoc-style warnings deliberately left to preserve
hand-written implementation rationale (plan-decision notes, race-condition
explanations).
This commit is contained in:
Joseph Doherty
2026-06-03 12:34:34 -04:00
parent c6d9b20d9f
commit bd6c0b4d3d
481 changed files with 2550 additions and 1668 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms.Tests/ScriptedAlarmEngineTests.cs
+37 -22
View File
@@ -32,6 +32,7 @@ public sealed class ScriptedAlarmEngineTests
PredicateScriptSource: predicate);
/// <summary>Verifies that LoadAsync compiles the alarm predicate and subscribes to all referenced upstream tags.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Load_compiles_and_subscribes_to_referenced_upstreams()
{
@@ -47,6 +48,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that compile failures across multiple alarms are aggregated into a single error.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Compile_failures_aggregated_into_one_error()
{
@@ -63,6 +65,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that an upstream tag change triggers predicate re-evaluation and emits an Activated event.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Upstream_change_re_evaluates_predicate_and_emits_Activated()
{
@@ -84,6 +87,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that clearing an upstream tag value emits a Cleared event and transitions the alarm to Inactive.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Clearing_upstream_emits_Cleared_event()
{
@@ -105,6 +109,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that the message template resolves current tag values at the moment of alarm emission.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Message_template_resolves_tag_values_at_emission()
{
@@ -130,6 +135,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that AcknowledgeAsync records the operator user and persists the ack state to the store.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Ack_records_user_and_persists_to_store()
{
@@ -150,6 +156,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that startup recovery restores the persisted ack state but re-derives the active state from the live predicate.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Startup_recovery_preserves_ack_but_rederives_active_from_predicate()
{
@@ -198,6 +205,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that a shelved alarm transitions its internal state on activation but suppresses the Activated emission.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Shelved_active_transitions_state_but_suppresses_emission()
{
@@ -222,6 +230,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that a runtime exception thrown by a predicate script leaves the alarm state unchanged and does not affect other alarms.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Predicate_runtime_exception_does_not_transition_state()
{
@@ -239,6 +248,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that a disabled alarm does not activate on predicate change and resumes normally after being re-enabled.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Disable_prevents_activation_until_re_enabled()
{
@@ -260,6 +270,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that AddCommentAsync appends to the audit trail without changing the alarm's active or ack state.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AddComment_appends_to_audit_without_state_change()
{
@@ -278,6 +289,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that predicate scripts are forbidden from calling SetVirtualTag, and that the exception is isolated without state change.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Predicate_scripts_cannot_SetVirtualTag()
{
@@ -302,6 +314,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that disposing the engine releases all upstream tag subscriptions.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Dispose_releases_upstream_subscriptions()
{
@@ -317,6 +330,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that concurrent reads of alarm state during dictionary mutations do not throw (regression for Core.ScriptedAlarms-001).</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Concurrent_reads_during_mutation_do_not_throw(/* Core.ScriptedAlarms-001 */)
{
@@ -386,6 +400,7 @@ public sealed class ScriptedAlarmEngineTests
// injectable clock — the clock and scriptTimeout constructor parameters
// exist for exactly this.
/// <summary>Verifies that a timed shelve automatically expires when the engine's shelving check runs past the unshelve time.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task TimedShelve_auto_expires_when_engine_shelving_check_runs(/* -012 (1) */)
{
@@ -423,6 +438,7 @@ public sealed class ScriptedAlarmEngineTests
// (2a) ConfirmAsync end-to-end through the engine.
/// <summary>Verifies that ConfirmAsync records the confirming user and emits a Confirmed event persisted to the store.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task ConfirmAsync_records_user_and_emits_Confirmed(/* -012 (2) */)
{
@@ -450,6 +466,7 @@ public sealed class ScriptedAlarmEngineTests
// (2b) TimedShelveAsync / UnshelveAsync end-to-end through the engine.
/// <summary>Verifies that TimedShelveAsync shelves with a deadline and UnshelveAsync removes the shelve before the timer expires.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task TimedShelveAsync_and_UnshelveAsync_round_trip(/* -012 (2) */)
{
@@ -478,6 +495,7 @@ public sealed class ScriptedAlarmEngineTests
// (2c) EnableAsync end-to-end through the engine.
/// <summary>Verifies that EnableAsync transitions the alarm back to Enabled state and emits an Enabled event.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task EnableAsync_re_enables_after_disable(/* -012 (2) */)
{
@@ -501,6 +519,7 @@ public sealed class ScriptedAlarmEngineTests
// the engine or prevent subsequent alarm state transitions. The engine logs
// the exception and continues operating; any later alarm changes still work.
/// <summary>Verifies that an exception thrown by an OnEvent subscriber is isolated and does not crash the engine or prevent further state transitions.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task OnEvent_subscriber_exception_does_not_crash_engine(/* -012 (3) */)
{
@@ -534,6 +553,7 @@ public sealed class ScriptedAlarmEngineTests
// (4) IAlarmStateStore.SaveAsync failure — in-memory state must remain at the
// prior value after finding -007 fix (persist-before-update).
/// <summary>Verifies that a store SaveAsync failure leaves the in-memory alarm state at its prior value (persist-before-update invariant, finding -007).</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Store_save_failure_leaves_in_memory_state_unchanged(/* -012 (4) */)
{
@@ -565,6 +585,7 @@ public sealed class ScriptedAlarmEngineTests
// (5) Re-entrant LoadAsync — the old timer must not keep firing after a second
// call (regression for finding -002: _shelvingTimer?.Dispose() fix).
/// <summary>Verifies that a second LoadAsync call disposes the prior shelving timer so it does not keep firing after reload (regression for finding -002).</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Second_LoadAsync_does_not_leak_old_timer(/* -012 (5) */)
{
@@ -598,6 +619,7 @@ public sealed class ScriptedAlarmEngineTests
// (6) Cold-start AreInputsReady guard — null value, Bad status, and Uncertain
// status inputs are all handled correctly.
/// <summary>Verifies that AreInputsReady blocks predicate evaluation when inputs have null values or Bad status codes, while Uncertain quality is accepted.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task AreInputsReady_blocks_evaluation_for_null_and_bad_inputs(/* -012 (6) */)
{
@@ -635,6 +657,7 @@ public sealed class ScriptedAlarmEngineTests
// not deadlock against _evalGate. Both regressions are covered here.
// -------------------------------------------------------------------------
/// <summary>Verifies that an OnEvent subscriber can call engine methods (e.g. AcknowledgeAsync) without deadlocking against the evaluation gate (regression for Core.ScriptedAlarms-003).</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task OnEvent_subscriber_can_call_back_into_engine_without_deadlock(/* -003 */)
{
@@ -748,6 +771,7 @@ public sealed class ScriptedAlarmEngineTests
// to a (possibly disposed) store after the engine has returned.
// -------------------------------------------------------------------------
/// <summary>Verifies that Dispose blocks until in-flight background re-evaluation tasks complete, preventing the engine from outliving its store (regression for Core.ScriptedAlarms-006).</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Dispose_drains_in_flight_reevaluation_tasks(/* -006 */)
{
@@ -794,6 +818,7 @@ public sealed class ScriptedAlarmEngineTests
// explicitly. The two policies are documented in docs/ScriptedAlarms.md.
// -------------------------------------------------------------------------
/// <summary>Verifies that Uncertain-quality inputs are accepted by the predicate but rendered as "{?}" in the operator-facing message template (Core.ScriptedAlarms-010).</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Uncertain_quality_drives_predicate_but_renders_question_mark_in_message(/* -010 */)
{
@@ -842,6 +867,7 @@ public sealed class ScriptedAlarmEngineTests
// consumers).
// -------------------------------------------------------------------------
/// <summary>Verifies that the Comments collection is an ImmutableList, enabling O(log n) append and satisfying IReadOnlyList consumers (Core.ScriptedAlarms-008).</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Comments_collection_uses_ImmutableList_for_efficient_append(/* -008 */)
{
@@ -907,29 +933,22 @@ public sealed class ScriptedAlarmEngineTests
/// <summary>Gets or sets a value indicating whether the next SaveAsync call should throw a simulated failure.</summary>
public bool FailSave { get; set; }
/// <summary>Loads an alarm condition state by ID from the inner store.</summary>
/// <param name="alarmId">The ID of the alarm condition state to load.</param>
/// <param name="ct">A cancellation token.</param>
/// <inheritdoc />
public Task<AlarmConditionState?> LoadAsync(string alarmId, CancellationToken ct)
=> _inner.LoadAsync(alarmId, ct);
/// <summary>Loads all alarm condition states from the inner store.</summary>
/// <param name="ct">A cancellation token.</param>
/// <inheritdoc />
public Task<IReadOnlyList<AlarmConditionState>> LoadAllAsync(CancellationToken ct)
=> _inner.LoadAllAsync(ct);
/// <summary>Saves an alarm condition state, optionally throwing if FailSave is set.</summary>
/// <param name="state">The alarm condition state to save.</param>
/// <param name="ct">A cancellation token.</param>
/// <inheritdoc />
public Task SaveAsync(AlarmConditionState state, CancellationToken ct)
{
if (FailSave) throw new InvalidOperationException("Simulated store failure");
return _inner.SaveAsync(state, ct);
}
/// <summary>Removes an alarm condition state by ID from the inner store.</summary>
/// <param name="alarmId">The ID of the alarm condition state to remove.</param>
/// <param name="ct">A cancellation token.</param>
/// <inheritdoc />
public Task RemoveAsync(string alarmId, CancellationToken ct)
=> _inner.RemoveAsync(alarmId, ct);
}
@@ -946,20 +965,15 @@ public sealed class ScriptedAlarmEngineTests
/// <summary>Gets a value indicating whether a SaveAsync call is currently blocked waiting on BlockNextSave.</summary>
public bool SaveInProgress { get; private set; }
/// <summary>Loads an alarm condition state by ID from the inner store.</summary>
/// <param name="alarmId">The ID of the alarm condition state to load.</param>
/// <param name="ct">A cancellation token.</param>
/// <inheritdoc />
public Task<AlarmConditionState?> LoadAsync(string alarmId, CancellationToken ct)
=> _inner.LoadAsync(alarmId, ct);
/// <summary>Loads all alarm condition states from the inner store.</summary>
/// <param name="ct">A cancellation token.</param>
/// <inheritdoc />
public Task<IReadOnlyList<AlarmConditionState>> LoadAllAsync(CancellationToken ct)
=> _inner.LoadAllAsync(ct);
/// <summary>Saves an alarm condition state, optionally blocking on BlockNextSave gate.</summary>
/// <param name="state">The alarm condition state to save.</param>
/// <param name="ct">A cancellation token.</param>
/// <inheritdoc />
public async Task SaveAsync(AlarmConditionState state, CancellationToken ct)
{
var gate = BlockNextSave;
@@ -973,9 +987,7 @@ public sealed class ScriptedAlarmEngineTests
await _inner.SaveAsync(state, ct).ConfigureAwait(false);
}
/// <summary>Removes an alarm condition state by ID from the inner store.</summary>
/// <param name="alarmId">The ID of the alarm condition state to remove.</param>
/// <param name="ct">A cancellation token.</param>
/// <inheritdoc />
public Task RemoveAsync(string alarmId, CancellationToken ct)
=> _inner.RemoveAsync(alarmId, ct);
}
@@ -983,6 +995,7 @@ public sealed class ScriptedAlarmEngineTests
// --- Core.ScriptedAlarms-009: per-alarm evaluation-scratch reuse ---
/// <summary>Verifies that re-evaluations reuse the same read cache dictionary instance instead of allocating a new one.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Reevaluation_reuses_the_same_read_cache_dictionary()
{
@@ -1016,6 +1029,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that re-evaluations reuse the same predicate context instance across evaluations.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Reevaluation_reuses_the_same_predicate_context()
{
@@ -1042,6 +1056,7 @@ public sealed class ScriptedAlarmEngineTests
}
/// <summary>Verifies that LoadAsync clears prior evaluation scratch so new alarms use fresh scratch.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task LoadAsync_drops_the_prior_generations_scratch()
{