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.
2026-06-03 11:39:32 -04:00
parent a050170414
commit eabf270d71
208 changed files with 867 additions and 114 deletions
@@ -89,6 +89,7 @@ public static class AuditEndpoints
    /// Registers the <c>/api/audit/query</c> and <c>/api/audit/export</c> minimal-API endpoints.
    /// </summary>
    /// <param name="endpoints">The endpoint route builder to register routes on.</param>
+    /// <returns>The same <paramref name="endpoints"/> builder, for chaining.</returns>
    public static IEndpointRouteBuilder MapAuditAPI(this IEndpointRouteBuilder endpoints)
    {
        endpoints.MapGet("/api/audit/query", (Delegate)HandleQuery);
@@ -104,6 +105,7 @@ public static class AuditEndpoints
    /// Handles <c>GET /api/audit/query</c>: authenticates, checks the OperationalAudit permission, and returns a keyset-paged JSON result.
    /// </summary>
    /// <param name="context">The HTTP context for the current request.</param>
+    /// <returns>A task that resolves to the HTTP result (200 JSON page, 401, or 403).</returns>
    internal static async Task<IResult> HandleQuery(HttpContext context)
    {
        var auth = await AuthenticateAsync(context);
@@ -163,6 +165,7 @@ public static class AuditEndpoints
    /// Handles <c>GET /api/audit/export</c>: authenticates, checks the AuditExport permission, and streams the matching rows as CSV or JSONL.
    /// </summary>
    /// <param name="context">The HTTP context for the current request.</param>
+    /// <returns>A task that resolves to the HTTP result (streaming CSV/JSONL, 400, 401, 403, or 501).</returns>
    internal static async Task<IResult> HandleExport(HttpContext context)
    {
        var auth = await AuthenticateAsync(context);
@@ -401,6 +404,8 @@ public static class AuditEndpoints
    /// with the permitted set) returns <c>null</c> so the caller gets a 403 rather
    /// than silently empty results.
    /// </summary>
+    /// <param name="filter">The caller-supplied audit-log query filter to scope.</param>
+    /// <param name="user">The authenticated user whose permitted site IDs constrain the filter.</param>
    /// <returns>
    /// The restricted filter, or <c>null</c> if the caller explicitly asked for
    /// sites entirely outside their permitted set.
@@ -455,6 +460,7 @@ public static class AuditEndpoints
    /// builder — so do NOT "fix" the two to a single key name.
    /// </remarks>
    /// <param name="query">The HTTP query string collection to parse filter parameters from.</param>
+    /// <returns>An <see cref="AuditLogQueryFilter"/> built from the supplied query parameters.</returns>
    public static AuditLogQueryFilter ParseFilter(IQueryCollection query)
    {
        var channels = AuditQueryParamParsers.ParseEnumList<AuditChannel>(query["channel"]);
@@ -506,6 +512,7 @@ public static class AuditEndpoints
    /// keyset cursor requires the pair together).
    /// </summary>
    /// <param name="query">The HTTP query string collection to parse paging parameters from.</param>
+    /// <returns>An <see cref="AuditLogPaging"/> built from the supplied query parameters.</returns>
    public static AuditLogPaging ParsePaging(IQueryCollection query)
    {
        int pageSize = DefaultPageSize;
@@ -576,6 +583,7 @@ public static class AuditEndpoints
    /// Formats a single <see cref="AuditEvent"/> as an RFC 4180 CSV row matching <see cref="CsvHeader"/>.
    /// </summary>
    /// <param name="evt">The audit event to format.</param>
+    /// <returns>An RFC 4180 CSV row string (no trailing newline) for the supplied event.</returns>
    public static string FormatCsvRow(AuditExportRow evt)
    {
        var sb = new StringBuilder(256);
@@ -63,6 +63,8 @@ public sealed record AuditExportRow
    public AuditForwardState? ForwardState { get; init; }

    /// <summary>Decomposes a canonical <see cref="AuditEvent"/> into this flat export shape.</summary>
+    /// <param name="evt">The audit event to decompose into the flat export row.</param>
+    /// <returns>A new <see cref="AuditExportRow"/> populated from the decomposed canonical row.</returns>
    public static AuditExportRow From(AuditEvent evt)
    {
        var r = AuditRowProjection.Decompose(evt);
@@ -33,6 +33,7 @@ public class DebugStreamHub : Hub
    /// <param name="roles">Roles held by the connected user.</param>
    /// <param name="permittedSiteIds">Site ids the user is scoped to; empty means system-wide.</param>
    /// <param name="instanceSiteId">Site id of the instance being subscribed to.</param>
+    /// <returns><see langword="true"/> if the user may subscribe to the instance; otherwise <see langword="false"/>.</returns>
    public static bool IsInstanceAccessAllowed(
        IReadOnlyCollection<string> roles,
        IReadOnlyCollection<string> permittedSiteIds,
@@ -134,6 +135,7 @@ public class DebugStreamHub : Hub
    /// Sends the initial snapshot immediately, then streams incremental changes.
    /// </summary>
    /// <param name="instanceId">Database id of the instance to subscribe to.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task SubscribeInstance(int instanceId)
    {
        // Stop any existing subscription for this connection
@@ -222,6 +224,7 @@ public class DebugStreamHub : Hub
    /// <summary>
    /// Unsubscribes from the current debug stream.
    /// </summary>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public Task UnsubscribeInstance()
    {
        if (Context.Items.TryGetValue(SessionIdKey, out var sessionIdObj) && sessionIdObj is string sessionId)
@@ -59,6 +59,7 @@ public class ManagementActor : ReceiveActor
    /// makes the contract correct ahead of any future worker actors (finding
    /// ManagementService-005).
    /// </summary>
+    /// <returns>A one-for-one Resume strategy with no retry limit.</returns>
    public static SupervisorStrategy CreateSupervisorStrategy() =>
        new OneForOneStrategy(
            maxNrOfRetries: -1,
@@ -85,6 +86,7 @@ public class ManagementActor : ReceiveActor
    /// serializer the HTTP endpoint uses — with cycle-safe settings.
    /// </summary>
    /// <param name="result">The command result object to serialize, or null.</param>
+    /// <returns>The JSON string representation of <paramref name="result"/>, or <c>"null"</c> when null.</returns>
    public static string SerializeResult(object? result) =>
        JsonSerializer.Serialize(result, ResultSerializerOptions);

@@ -24,6 +24,7 @@ public static class ManagementEndpoints
    /// zero/negative timeout would make every management call fail immediately.
    /// </summary>
    /// <param name="options">The management service options, or <c>null</c> if not configured.</param>
+    /// <returns>The configured timeout, or <see cref="DefaultAskTimeout"/> when none is set.</returns>
    public static TimeSpan ResolveAskTimeout(ManagementServiceOptions? options)
    {
        if (options is { CommandTimeout: { Ticks: > 0 } configured })
@@ -33,6 +34,7 @@ public static class ManagementEndpoints

    /// <summary>Registers the <c>POST /management</c> endpoint on the given route builder.</summary>
    /// <param name="endpoints">The route builder to add the endpoint to.</param>
+    /// <returns>The same <paramref name="endpoints"/> instance for chaining.</returns>
    public static IEndpointRouteBuilder MapManagementAPI(this IEndpointRouteBuilder endpoints)
    {
        endpoints.MapPost("/management", (Delegate)HandleRequest);
@@ -166,9 +168,11 @@ public static class ManagementEndpoints
    {
        /// <summary>Creates a successful parse result wrapping the given command.</summary>
        /// <param name="command">The strongly-typed command object that was parsed.</param>
+        /// <returns>A successful <see cref="CommandParseResult"/> containing the parsed command.</returns>
        public static CommandParseResult Ok(object command) => new(true, command, null, null);
        /// <summary>Creates a failed parse result with the given error message.</summary>
        /// <param name="message">Human-readable description of the parse failure.</param>
+        /// <returns>A failed <see cref="CommandParseResult"/> with the error message and <c>BAD_REQUEST</c> code.</returns>
        public static CommandParseResult Fail(string message) => new(false, null, message, "BAD_REQUEST");
    }

@@ -179,6 +183,7 @@ public static class ManagementEndpoints
    /// case does not allocate a throwaway document (finding ManagementService-006).
    /// </summary>
    /// <param name="body">The raw JSON request body string.</param>
+    /// <returns>A <see cref="CommandParseResult"/> with the deserialized command on success, or an error on failure.</returns>
    public static CommandParseResult ParseCommand(string body)
    {
        using JsonDocument doc = ParseDocument(body, out var parseError);
@@ -8,6 +8,7 @@ public static class ServiceCollectionExtensions
    /// Registers the management actor holder and management service options.
    /// </summary>
    /// <param name="services">The service collection to register into.</param>
+    /// <returns>The <paramref name="services"/> instance for chaining.</returns>
    public static IServiceCollection AddManagementService(this IServiceCollection services)
    {
        services.AddSingleton<ManagementActorHolder>();