docs: add XML doc comments across src + Sister Projects section in CLAUDE.md

Bulk CommentChecker pass: fills in <param>/<inheritdoc> tags on public
APIs across all 23 src/ projects so the doc-coverage gate is green. Also
adds a Sister Projects section to CLAUDE.md pointing at the MxAccess
Gateway and OtOpcUa sibling repos, and gitignores local credential
captures (*login*.txt) and the wonder-app-vd03 deploy/ artifacts.
This commit is contained in:
Joseph Doherty
2026-05-28 01:55:24 -04:00
parent 6731845473
commit 1eb6e972b0
381 changed files with 5788 additions and 532 deletions
@@ -8,19 +8,62 @@ public record TagValue(object? Value, QualityCode Quality, DateTimeOffset Timest
public record ReadResult(bool Success, TagValue? Value, string? ErrorMessage);
public record WriteResult(bool Success, string? ErrorMessage);
/// <summary>Callback invoked when a subscribed tag value changes.</summary>
/// <param name="tagPath">The tag path whose value has changed.</param>
/// <param name="value">The new tag value including quality and timestamp.</param>
public delegate void SubscriptionCallback(string tagPath, TagValue value);
public interface IDataConnection : IAsyncDisposable
{
/// <summary>Establishes the protocol connection using the provided connection details.</summary>
/// <param name="connectionDetails">Protocol-specific key-value configuration pairs.</param>
/// <param name="cancellationToken">Cancellation token.</param>
Task ConnectAsync(IDictionary<string, string> connectionDetails, CancellationToken cancellationToken = default);
/// <summary>Gracefully terminates the protocol connection.</summary>
/// <param name="cancellationToken">Cancellation token.</param>
Task DisconnectAsync(CancellationToken cancellationToken = default);
/// <summary>Subscribes to value-change notifications for a tag path; returns a subscription ID.</summary>
/// <param name="tagPath">The tag path to subscribe to.</param>
/// <param name="callback">Callback invoked on each value change.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>A subscription ID that can be passed to <see cref="UnsubscribeAsync"/>.</returns>
Task<string> SubscribeAsync(string tagPath, SubscriptionCallback callback, CancellationToken cancellationToken = default);
/// <summary>Cancels an active subscription by its ID.</summary>
/// <param name="subscriptionId">The subscription ID returned by <see cref="SubscribeAsync"/>.</param>
/// <param name="cancellationToken">Cancellation token.</param>
Task UnsubscribeAsync(string subscriptionId, CancellationToken cancellationToken = default);
/// <summary>Reads the current value of a single tag.</summary>
/// <param name="tagPath">The tag path to read.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>The read result containing the value or an error.</returns>
Task<ReadResult> ReadAsync(string tagPath, CancellationToken cancellationToken = default);
/// <summary>Reads the current values of multiple tags in a single round-trip.</summary>
/// <param name="tagPaths">The tag paths to read.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>A dictionary of tag paths to their read results.</returns>
Task<IReadOnlyDictionary<string, ReadResult>> ReadBatchAsync(IEnumerable<string> tagPaths, CancellationToken cancellationToken = default);
/// <summary>Writes a value to a single tag.</summary>
/// <param name="tagPath">The tag path to write.</param>
/// <param name="value">The value to write.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>The write result indicating success or failure.</returns>
Task<WriteResult> WriteAsync(string tagPath, object? value, CancellationToken cancellationToken = default);
/// <summary>Writes values to multiple tags in a single round-trip.</summary>
/// <param name="values">A dictionary of tag paths to values.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>A dictionary of tag paths to their write results.</returns>
Task<IReadOnlyDictionary<string, WriteResult>> WriteBatchAsync(IDictionary<string, object?> values, CancellationToken cancellationToken = default);
/// <summary>Writes a batch of values, then writes a flag and waits for a specific response value within the timeout.</summary>
/// <param name="values">Tag values to write before the flag.</param>
/// <param name="flagPath">Tag path of the trigger flag.</param>
/// <param name="flagValue">Value to write to the flag tag.</param>
/// <param name="responsePath">Tag path to monitor for the expected response value.</param>
/// <param name="responseValue">The response value that indicates completion.</param>
/// <param name="timeout">Maximum time to wait for the response.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns><c>true</c> if the response value was observed within the timeout; otherwise <c>false</c>.</returns>
Task<bool> WriteBatchAndWaitAsync(IDictionary<string, object?> values, string flagPath, object? flagValue, string responsePath, object? responseValue, TimeSpan timeout, CancellationToken cancellationToken = default);
/// <summary>Current connection health status.</summary>
ConnectionHealth Status { get; }
/// <summary>