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.
This commit is contained in:
Joseph Doherty
2026-06-03 11:39:32 -04:00
parent a050170414
commit eabf270d71
208 changed files with 867 additions and 114 deletions
@@ -45,6 +45,7 @@ public static class ApiMethodKeyScopeReconciler
/// <param name="currentMethodsByKey">Each affected key's CURRENT full scope set, keyed by KeyId.
/// Read fresh from the seam right before reconciling so concurrent edits do not get clobbered.</param>
/// <param name="keyNamesById">Display names by KeyId, for human-readable empty-scope messages.</param>
/// <returns>A <see cref="ReconcileResult"/> with the scope updates to apply and any empty-scope warnings.</returns>
public static ReconcileResult Reconcile(
string methodName,
IReadOnlySet<string> selectedKeyIds,
@@ -70,6 +70,8 @@ public sealed record AuditEventView
/// <summary>
/// Decomposes a canonical <see cref="AuditEvent"/> into a flat view for the UI.
/// </summary>
/// <param name="evt">The canonical audit event to decompose.</param>
/// <returns>A flat <see cref="AuditEventView"/> populated from the event's top-level and details fields.</returns>
public static AuditEventView From(AuditEvent evt)
{
var r = AuditRowProjection.Decompose(evt);
@@ -42,6 +42,7 @@ public interface IAuditLogExportService
/// enough to amortise the per-query overhead, small enough that one page in
/// memory is bounded.
/// </param>
/// <returns>A task that completes when all matching rows (up to <paramref name="maxRows"/>) have been written to <paramref name="output"/>.</returns>
Task ExportAsync(
AuditLogQueryFilter filter,
int maxRows,
@@ -176,6 +177,7 @@ public sealed class AuditLogExportService : IAuditLogExportService
/// cleanly on another.
/// </summary>
/// <param name="evt">The audit event view to format as a CSV row.</param>
/// <returns>An RFC 4180 CSV row string (no trailing newline) for the supplied event.</returns>
internal static string FormatCsvRow(AuditEventView evt)
{
var sb = new StringBuilder(256);
@@ -28,6 +28,7 @@ public interface IAuditLogQueryService
/// <param name="filter">Filter criteria applied to the audit log query.</param>
/// <param name="paging">Optional paging cursor; defaults to first page when null.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>A task that resolves to a page of audit event views matching the filter.</returns>
Task<IReadOnlyList<AuditEventView>> QueryAsync(
AuditLogQueryFilter filter,
AuditLogPaging? paging = null,
@@ -57,6 +58,7 @@ public interface IAuditLogQueryService
/// dashboard.
/// </remarks>
/// <param name="ct">Cancellation token.</param>
/// <returns>A task that resolves to the current audit KPI snapshot.</returns>
Task<AuditLogKpiSnapshot> GetKpiSnapshotAsync(CancellationToken ct = default);
/// <summary>
@@ -76,6 +78,7 @@ public interface IAuditLogQueryService
/// </remarks>
/// <param name="executionId">Any execution id in the chain to look up.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>A task that resolves to the flat list of execution tree nodes in the chain.</returns>
Task<IReadOnlyList<ExecutionTreeNode>> GetExecutionTreeAsync(
Guid executionId,
CancellationToken ct = default);
@@ -90,5 +93,6 @@ public interface IAuditLogQueryService
/// filter affordance.
/// </summary>
/// <param name="ct">Cancellation token.</param>
/// <returns>A task that resolves to the distinct non-null source node names present in the audit log.</returns>
Task<IReadOnlyList<string>> GetDistinctSourceNodesAsync(CancellationToken ct = default);
}
@@ -31,6 +31,7 @@ public interface IBindingTester
/// <param name="connectionName">Name of the site-local data connection — the site's <c>DataConnectionManagerActor</c> indexes its children by name.</param>
/// <param name="tagPaths">Tag paths to read.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>A task that resolves to the read outcomes for all requested tag paths.</returns>
Task<ReadTagValuesResult> ReadAsync(
string siteId,
string connectionName,
@@ -29,6 +29,7 @@ public interface IBrowseService
/// <param name="connectionName">Name of the site-local data connection to browse against — the site's <c>DataConnectionManagerActor</c> indexes its children by name.</param>
/// <param name="parentNodeId">Node to browse, or <c>null</c> to browse from the server root.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>A task that resolves to a <see cref="BrowseNodeResult"/> containing child nodes or a <see cref="BrowseFailure"/> on error.</returns>
Task<BrowseNodeResult> BrowseChildrenAsync(
string siteId,
string connectionName,