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.Tests/GenericDriverNodeManagerTests.cs
+36 -60
View File
@@ -15,6 +15,7 @@ public sealed class GenericDriverNodeManagerTests
/// This is the plumbing that PR 16's concrete OPC UA builder will use to update the actual
/// AlarmConditionState nodes.
/// </summary>
/// <returns>A task that represents the asynchronous test operation.</returns>
[Fact]
public async Task Alarm_events_are_routed_to_the_sink_registered_for_the_matching_source_node_id()
{
@@ -45,6 +46,7 @@ public sealed class GenericDriverNodeManagerTests
}
/// <summary>Verifies that non-alarm variables do not register sinks in the alarm tracker.</summary>
/// <returns>A task that represents the asynchronous test operation.</returns>
[Fact]
public async Task Non_alarm_variables_do_not_register_sinks()
{
@@ -59,6 +61,7 @@ public sealed class GenericDriverNodeManagerTests
}
/// <summary>Verifies that alarm events with unknown source node IDs are silently dropped.</summary>
/// <returns>A task that represents the asynchronous test operation.</returns>
[Fact]
public async Task Unknown_source_node_id_is_dropped_silently()
{
@@ -74,6 +77,7 @@ public sealed class GenericDriverNodeManagerTests
}
/// <summary>Verifies that disposing the node manager unsubscribes from alarm events.</summary>
/// <returns>A task that represents the asynchronous test operation.</returns>
[Fact]
public async Task Dispose_unsubscribes_from_OnAlarmEvent()
{
@@ -96,6 +100,7 @@ public sealed class GenericDriverNodeManagerTests
/// must unsubscribe the old alarm forwarder and clear the sink registry before re-walking,
/// so alarm transitions are not delivered twice.
/// </summary>
/// <returns>A task that represents the asynchronous test operation.</returns>
[Fact]
public async Task Second_BuildAddressSpaceAsync_Does_Not_Double_Fire_Alarms()
{
@@ -121,6 +126,7 @@ public sealed class GenericDriverNodeManagerTests
}
/// <summary>Verifies that a second call to BuildAddressSpaceAsync clears the old sink registry.</summary>
/// <returns>A task that represents the asynchronous test operation.</returns>
[Fact]
public async Task Second_BuildAddressSpaceAsync_Clears_Old_Sink_Registry()
{
@@ -137,6 +143,7 @@ public sealed class GenericDriverNodeManagerTests
}
/// <summary>Verifies that calling BuildAddressSpaceAsync after disposal throws ObjectDisposedException.</summary>
/// <returns>A task that represents the asynchronous test operation.</returns>
[Fact]
public async Task BuildAddressSpaceAsync_After_Dispose_Throws_ObjectDisposedException()
{
@@ -154,6 +161,7 @@ public sealed class GenericDriverNodeManagerTests
/// out of <c>BuildAddressSpaceAsync</c> unhandled so the Server layer's per-driver try/catch
/// (<c>OpcUaApplicationHost.PopulateAddressSpaces</c>) can mark the subtree Faulted.
/// </summary>
/// <returns>A task that represents the asynchronous test operation.</returns>
[Fact]
public async Task BuildAddressSpaceAsync_Propagates_Discovery_Exceptions_To_Caller()
{
@@ -169,33 +177,25 @@ public sealed class GenericDriverNodeManagerTests
/// <summary>Driver whose DiscoverAsync throws — exercises the exception-isolation boundary.</summary>
private sealed class ThrowingDiscoveryDriver : IDriver, ITagDiscovery
{
/// <summary>Gets the driver instance identifier.</summary>
/// <inheritdoc />
public string DriverInstanceId => "throwing";
/// <summary>Gets the driver type name.</summary>
/// <inheritdoc />
public string DriverType => "Throwing";
/// <summary>Initializes the driver with configuration.</summary>
/// <param name="_">Configuration JSON (unused in test double).</param>
/// <param name="__">Cancellation token (unused in test double).</param>
/// <inheritdoc />
public Task InitializeAsync(string _, CancellationToken __) => Task.CompletedTask;
/// <summary>Reinitializes the driver with new configuration.</summary>
/// <param name="_">Configuration JSON (unused in test double).</param>
/// <param name="__">Cancellation token (unused in test double).</param>
/// <inheritdoc />
public Task ReinitializeAsync(string _, CancellationToken __) => Task.CompletedTask;
/// <summary>Shuts down the driver.</summary>
/// <param name="_">Cancellation token (unused in test double).</param>
/// <inheritdoc />
public Task ShutdownAsync(CancellationToken _) => Task.CompletedTask;
/// <summary>Gets the current health status of the driver.</summary>
/// <inheritdoc />
public DriverHealth GetHealth() => new(DriverState.Healthy, null, null);
/// <summary>Gets the memory footprint of the driver.</summary>
/// <inheritdoc />
public long GetMemoryFootprint() => 0;
/// <summary>Flushes optional caches in the driver.</summary>
/// <param name="_">Cancellation token (unused in test double).</param>
/// <inheritdoc />
public Task FlushOptionalCachesAsync(CancellationToken _) => Task.CompletedTask;
/// <summary>Discovers the address space by throwing an exception.</summary>
/// <param name="builder">The builder used to construct the address space.</param>
/// <param name="ct">Cancellation token.</param>
/// <inheritdoc />
public Task DiscoverAsync(IAddressSpaceBuilder builder, CancellationToken ct)
=> throw new InvalidOperationException("discovery boom");
}
@@ -204,35 +204,27 @@ public sealed class GenericDriverNodeManagerTests
private sealed class FakeDriver : IDriver, ITagDiscovery, IAlarmSource
{
/// <summary>Gets the driver instance identifier.</summary>
/// <inheritdoc />
public string DriverInstanceId => "fake";
/// <summary>Gets the driver type name.</summary>
/// <inheritdoc />
public string DriverType => "Fake";
/// <summary>Occurs when an alarm event is raised.</summary>
public event EventHandler<AlarmEventArgs>? OnAlarmEvent;
/// <summary>Initializes the driver with configuration.</summary>
/// <param name="driverConfigJson">Configuration JSON.</param>
/// <param name="ct">Cancellation token.</param>
/// <inheritdoc />
public Task InitializeAsync(string driverConfigJson, CancellationToken ct) => Task.CompletedTask;
/// <summary>Reinitializes the driver with new configuration.</summary>
/// <param name="driverConfigJson">Configuration JSON.</param>
/// <param name="ct">Cancellation token.</param>
/// <inheritdoc />
public Task ReinitializeAsync(string driverConfigJson, CancellationToken ct) => Task.CompletedTask;
/// <summary>Shuts down the driver.</summary>
/// <param name="ct">Cancellation token.</param>
/// <inheritdoc />
public Task ShutdownAsync(CancellationToken ct) => Task.CompletedTask;
/// <summary>Gets the current health status of the driver.</summary>
/// <inheritdoc />
public DriverHealth GetHealth() => new(DriverState.Healthy, DateTime.UtcNow, null);
/// <summary>Gets the memory footprint of the driver.</summary>
/// <inheritdoc />
public long GetMemoryFootprint() => 0;
/// <summary>Flushes optional caches in the driver.</summary>
/// <param name="ct">Cancellation token.</param>
/// <inheritdoc />
public Task FlushOptionalCachesAsync(CancellationToken ct) => Task.CompletedTask;
/// <summary>Discovers the address space and registers alarm conditions.</summary>
/// <param name="builder">The builder used to construct the address space.</param>
/// <param name="ct">Cancellation token.</param>
/// <inheritdoc />
public Task DiscoverAsync(IAddressSpaceBuilder builder, CancellationToken ct)
{
var folder = builder.Folder("Tank", "Tank");
@@ -253,25 +245,19 @@ public sealed class GenericDriverNodeManagerTests
/// <param name="args">The alarm event arguments.</param>
public void RaiseAlarm(AlarmEventArgs args) => OnAlarmEvent?.Invoke(this, args);
/// <summary>Subscribes to alarm events.</summary>
/// <param name="_">Tag references to subscribe to (unused in test double).</param>
/// <param name="__">Cancellation token (unused in test double).</param>
/// <inheritdoc />
public Task<IAlarmSubscriptionHandle> SubscribeAlarmsAsync(IReadOnlyList<string> _, CancellationToken __)
=> Task.FromResult<IAlarmSubscriptionHandle>(new FakeHandle("sub"));
/// <summary>Unsubscribes from alarm events.</summary>
/// <param name="_">The subscription handle (unused in test double).</param>
/// <param name="__">Cancellation token (unused in test double).</param>
/// <inheritdoc />
public Task UnsubscribeAlarmsAsync(IAlarmSubscriptionHandle _, CancellationToken __) => Task.CompletedTask;
/// <summary>Acknowledges alarm notifications.</summary>
/// <param name="_">Alarm acknowledgement requests (unused in test double).</param>
/// <param name="__">Cancellation token (unused in test double).</param>
/// <inheritdoc />
public Task AcknowledgeAsync(IReadOnlyList<AlarmAcknowledgeRequest> _, CancellationToken __) => Task.CompletedTask;
}
/// <summary>Test double for IAlarmSubscriptionHandle.</summary>
private sealed class FakeHandle(string diagnosticId) : IAlarmSubscriptionHandle
{
/// <summary>Gets the diagnostic identifier for this subscription.</summary>
/// <inheritdoc />
public string DiagnosticId { get; } = diagnosticId;
}
@@ -281,31 +267,22 @@ public sealed class GenericDriverNodeManagerTests
/// <summary>Gets the map of alarm sources to their sinks.</summary>
public Dictionary<string, RecordingSink> Alarms { get; } = new(StringComparer.OrdinalIgnoreCase);
/// <summary>Creates a folder in the address space.</summary>
/// <param name="_">The contained name (unused in test double).</param>
/// <param name="__">The display name (unused in test double).</param>
/// <inheritdoc />
public IAddressSpaceBuilder Folder(string _, string __) => this;
/// <summary>Creates a variable in the address space.</summary>
/// <param name="_">The contained name (unused in test double).</param>
/// <param name="__">The display name (unused in test double).</param>
/// <param name="info">The driver attribute information.</param>
/// <inheritdoc />
public IVariableHandle Variable(string _, string __, DriverAttributeInfo info)
=> new Handle(info.FullName, Alarms);
/// <summary>Adds a property to the current variable.</summary>
/// <param name="_">The property name (unused in test double).</param>
/// <param name="__">The data type (unused in test double).</param>
/// <param name="___">The initial value (unused in test double).</param>
/// <inheritdoc />
public void AddProperty(string _, DriverDataType __, object? ___) { }
/// <summary>Test double for IVariableHandle.</summary>
public sealed class Handle(string fullRef, Dictionary<string, RecordingSink> alarms) : IVariableHandle
{
/// <summary>Gets the full reference name for this variable.</summary>
/// <inheritdoc />
public string FullReference { get; } = fullRef;
/// <summary>Marks this variable as an alarm condition and registers its sink.</summary>
/// <param name="_">The alarm condition info (unused in test double).</param>
/// <inheritdoc />
public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo _)
{
var sink = new RecordingSink();
@@ -319,8 +296,7 @@ public sealed class GenericDriverNodeManagerTests
{
/// <summary>Gets the list of alarm transitions received by this sink.</summary>
public List<AlarmEventArgs> Received { get; } = new();
/// <summary>Records an alarm transition.</summary>
/// <param name="args">The alarm event arguments.</param>
/// <inheritdoc />
public void OnTransition(AlarmEventArgs args) => Received.Add(args);
}
}