docs(xml): fill missing XML doc comments + strip task-tracking refs across src (fixdocs)

Add missing <summary>/<param>/<returns>/<typeparam> tags and switch interface implementations to <inheritdoc/> across 106 files; strip project bookkeeping identifiers (Task NN, #05-TNN, PLAN-04, StoreAndForward-0NN) from shipped code comments while preserving the descriptive rationale. Comment-only: zero code-logic lines changed; solution builds 0/0. Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj
2026-07-10 08:23:56 -04:00
parent 75007b9edd
commit 5a878b78d4
106 changed files with 580 additions and 180 deletions
@@ -68,12 +68,20 @@ public sealed class ScriptCompileSurface
    public sealed class CompileInstance
    {
        /// <summary>Mirrors <c>ScriptRuntimeContext.GetAttribute</c>.</summary>
+        /// <param name="attributeName">The name of the attribute to read.</param>
+        /// <returns>The attribute's current value.</returns>
        public Task<object?> GetAttribute(string attributeName) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>ScriptRuntimeContext.SetAttribute</c>.</summary>
+        /// <param name="attributeName">The name of the attribute to write.</param>
+        /// <param name="value">The value to write to the attribute.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
        public Task SetAttribute(string attributeName, string value) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>ScriptRuntimeContext.CallScript</c>.</summary>
+        /// <param name="scriptName">The name of the script to invoke.</param>
+        /// <param name="parameters">Optional parameters passed to the script.</param>
+        /// <returns>The result returned by the invoked script.</returns>
        public Task<object?> CallScript(string scriptName, object? parameters = null) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>ScriptRuntimeContext.ExternalSystem</c>.</summary>
@@ -96,6 +104,11 @@ public sealed class ScriptCompileSurface
    public sealed class CompileExternalSystem
    {
        /// <summary>Mirrors <c>ExternalSystemHelper.Call</c>.</summary>
+        /// <param name="systemName">The name of the external system to call.</param>
+        /// <param name="methodName">The name of the method to invoke on the external system.</param>
+        /// <param name="parameters">Optional parameters passed to the call.</param>
+        /// <param name="cancellationToken">Token used to cancel the call.</param>
+        /// <returns>The result of the external system call.</returns>
        public Task<ExternalCallResult> Call(
            string systemName,
            string methodName,
@@ -104,6 +117,11 @@ public sealed class ScriptCompileSurface
            => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>ExternalSystemHelper.CachedCall</c>.</summary>
+        /// <param name="systemName">The name of the external system to call.</param>
+        /// <param name="methodName">The name of the method to invoke on the external system.</param>
+        /// <param name="parameters">Optional parameters passed to the call.</param>
+        /// <param name="cancellationToken">Token used to cancel the call.</param>
+        /// <returns>A tracking handle for the store-and-forward operation.</returns>
        public Task<TrackedOperationId> CachedCall(
            string systemName,
            string methodName,
@@ -116,10 +134,18 @@ public sealed class ScriptCompileSurface
    public sealed class CompileDatabase
    {
        /// <summary>Mirrors <c>DatabaseHelper.Connection</c>.</summary>
+        /// <param name="name">The name of the configured database connection.</param>
+        /// <param name="cancellationToken">Token used to cancel the operation.</param>
+        /// <returns>An open connection to the named database.</returns>
        public Task<DbConnection> Connection(string name, CancellationToken cancellationToken = default)
            => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>DatabaseHelper.CachedWrite</c>.</summary>
+        /// <param name="name">The name of the configured database connection.</param>
+        /// <param name="sql">The SQL statement to execute.</param>
+        /// <param name="parameters">Optional parameters bound to the SQL statement.</param>
+        /// <param name="cancellationToken">Token used to cancel the operation.</param>
+        /// <returns>A tracking handle for the store-and-forward write.</returns>
        public Task<TrackedOperationId> CachedWrite(
            string name,
            string sql,
@@ -132,9 +158,13 @@ public sealed class ScriptCompileSurface
    public sealed class CompileNotify
    {
        /// <summary>Mirrors <c>NotifyHelper.To</c>.</summary>
+        /// <param name="listName">The name of the notification list to target.</param>
+        /// <returns>A target used to send a notification to the named list.</returns>
        public CompileNotifyTarget To(string listName) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>NotifyHelper.Status</c>.</summary>
+        /// <param name="notificationId">The identifier of the notification to look up.</param>
+        /// <returns>The delivery status of the notification.</returns>
        public Task<NotificationDeliveryStatus> Status(string notificationId) => throw new NotSupportedException(CompileOnly);
    }

@@ -142,6 +172,10 @@ public sealed class ScriptCompileSurface
    public sealed class CompileNotifyTarget
    {
        /// <summary>Mirrors <c>NotifyTarget.Send</c>.</summary>
+        /// <param name="subject">The notification subject.</param>
+        /// <param name="message">The notification message body.</param>
+        /// <param name="cancellationToken">Token used to cancel the operation.</param>
+        /// <returns>The identifier of the enqueued notification.</returns>
        public Task<string> Send(string subject, string message, CancellationToken cancellationToken = default)
            => throw new NotSupportedException(CompileOnly);
    }
@@ -150,6 +184,10 @@ public sealed class ScriptCompileSurface
    public sealed class CompileScripts
    {
        /// <summary>Mirrors <c>ScriptCallHelper.CallShared</c>.</summary>
+        /// <param name="scriptName">The name of the shared script to invoke.</param>
+        /// <param name="parameters">Optional parameters passed to the script.</param>
+        /// <param name="cancellationToken">Token used to cancel the operation.</param>
+        /// <returns>The result returned by the invoked shared script.</returns>
        public Task<object?> CallShared(
            string scriptName,
            object? parameters = null,
@@ -161,6 +199,9 @@ public sealed class ScriptCompileSurface
    public sealed class CompileTracking
    {
        /// <summary>Mirrors <c>TrackingHelper.Status</c>.</summary>
+        /// <param name="trackedOperationId">The tracking handle returned by a cached call or write.</param>
+        /// <param name="cancellationToken">Token used to cancel the operation.</param>
+        /// <returns>The current tracking status snapshot, or <c>null</c> if not found.</returns>
        public Task<TrackingStatusSnapshot?> Status(
            TrackedOperationId trackedOperationId,
            CancellationToken cancellationToken = default)
@@ -171,6 +212,7 @@ public sealed class ScriptCompileSurface
    public sealed class CompileAttributeAccessor
    {
        /// <summary>Mirrors <c>AttributeAccessor.this[string]</c>.</summary>
+        /// <param name="key">The name of the attribute to get or set.</param>
        public object? this[string key]
        {
            get => throw new NotSupportedException(CompileOnly);
@@ -178,23 +220,61 @@ public sealed class ScriptCompileSurface
        }

        /// <summary>Mirrors <c>AttributeAccessor.GetAsync</c>.</summary>
+        /// <param name="key">The name of the attribute to read.</param>
+        /// <returns>The attribute's current value.</returns>
        public Task<object?> GetAsync(string key) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>AttributeAccessor.SetAsync</c>.</summary>
+        /// <param name="key">The name of the attribute to write.</param>
+        /// <param name="value">The value to write to the attribute.</param>
+        /// <returns>A task that represents the asynchronous operation.</returns>
        public Task SetAsync(string key, object? value) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>AttributeAccessor.Resolve</c>.</summary>
+        /// <param name="key">The name of the attribute to resolve.</param>
+        /// <returns>The resolved attribute path.</returns>
        public string Resolve(string key) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>AttributeAccessor.WaitAsync</c>.</summary>
+        /// <param name="key">The name of the attribute to wait on.</param>
+        /// <param name="targetValue">The value to wait for.</param>
+        /// <param name="timeout">The maximum time to wait.</param>
+        /// <param name="requireGoodQuality">Whether the attribute must also have good quality before the wait succeeds.</param>
+        /// <returns><c>true</c> if the target value was observed before the timeout elapsed; otherwise <c>false</c>.</returns>
        public Task<bool> WaitAsync(string key, object? targetValue, TimeSpan timeout, bool requireGoodQuality = false) => throw new NotSupportedException(CompileOnly);
+
+        /// <summary>Mirrors <c>AttributeAccessor.WaitAsync</c>.</summary>
+        /// <param name="key">The name of the attribute to wait on.</param>
+        /// <param name="predicate">A predicate evaluated against successive attribute values.</param>
+        /// <param name="timeout">The maximum time to wait.</param>
+        /// <param name="requireGoodQuality">Whether the attribute must also have good quality before the wait succeeds.</param>
+        /// <returns><c>true</c> if the predicate was satisfied before the timeout elapsed; otherwise <c>false</c>.</returns>
        public Task<bool> WaitAsync(string key, Func<object?, bool> predicate, TimeSpan timeout, bool requireGoodQuality = false) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>AttributeAccessor.WaitForAsync</c>.</summary>
+        /// <param name="key">The name of the attribute to wait on.</param>
+        /// <param name="targetValue">The value to wait for.</param>
+        /// <param name="timeout">The maximum time to wait.</param>
+        /// <param name="requireGoodQuality">Whether the attribute must also have good quality before the wait succeeds.</param>
+        /// <returns>The outcome of the wait, including whether it succeeded or timed out.</returns>
        public Task<WaitResult> WaitForAsync(string key, object? targetValue, TimeSpan timeout, bool requireGoodQuality = false) => throw new NotSupportedException(CompileOnly);
+
+        /// <summary>Mirrors <c>AttributeAccessor.WaitForAsync</c>.</summary>
+        /// <param name="key">The name of the attribute to wait on.</param>
+        /// <param name="predicate">A predicate evaluated against successive attribute values.</param>
+        /// <param name="timeout">The maximum time to wait.</param>
+        /// <param name="requireGoodQuality">Whether the attribute must also have good quality before the wait succeeds.</param>
+        /// <returns>The outcome of the wait, including whether it succeeded or timed out.</returns>
        public Task<WaitResult> WaitForAsync(string key, Func<object?, bool> predicate, TimeSpan timeout, bool requireGoodQuality = false) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>AttributeAccessor.WriteBatchAndWaitAsync</c>.</summary>
+        /// <param name="values">The set of attribute values to write as a batch.</param>
+        /// <param name="flagKey">The name of the flag attribute signaling the write.</param>
+        /// <param name="flagValue">The value written to the flag attribute.</param>
+        /// <param name="responseKey">The name of the attribute to observe for a response.</param>
+        /// <param name="responseValue">The value to wait for on the response attribute.</param>
+        /// <param name="timeout">The maximum time to wait for the response.</param>
+        /// <returns><c>true</c> if the response value was observed before the timeout elapsed; otherwise <c>false</c>.</returns>
        public Task<bool> WriteBatchAndWaitAsync(IReadOnlyDictionary<string, object?> values, string flagKey, object? flagValue, string responseKey, object? responseValue, TimeSpan timeout) => throw new NotSupportedException(CompileOnly);
    }

@@ -202,6 +282,7 @@ public sealed class ScriptCompileSurface
    public sealed class CompileChildrenAccessor
    {
        /// <summary>Mirrors <c>ChildrenAccessor.this[string]</c>.</summary>
+        /// <param name="compositionName">The name of the composed child to access.</param>
        public CompileCompositionAccessor this[string compositionName] => throw new NotSupportedException(CompileOnly);
    }

@@ -212,9 +293,14 @@ public sealed class ScriptCompileSurface
        public CompileAttributeAccessor Attributes => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>CompositionAccessor.CallScript</c>.</summary>
+        /// <param name="scriptName">The name of the script to invoke.</param>
+        /// <param name="parameters">Optional parameters passed to the script.</param>
+        /// <returns>The result returned by the invoked script.</returns>
        public Task<object?> CallScript(string scriptName, object? parameters = null) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>CompositionAccessor.ResolveScript</c>.</summary>
+        /// <param name="scriptName">The name of the script to resolve.</param>
+        /// <returns>The resolved script path.</returns>
        public string ResolveScript(string scriptName) => throw new NotSupportedException(CompileOnly);

        /// <summary>Mirrors <c>CompositionAccessor.Path</c>.</summary>
@@ -319,6 +319,7 @@ public static class ScriptTrustPolicy
    /// fallback hole is closed) without depending on the host actually
    /// lacking a TPA list.
    /// </summary>
+    /// <returns>The minimal fallback reference set (default assemblies plus forbidden-API anchor assemblies).</returns>
    public static IReadOnlyList<MetadataReference> BuildMinimalFallbackReferences()
    {
        var byPath = new Dictionary<string, MetadataReference>(StringComparer.OrdinalIgnoreCase);
@@ -313,6 +313,8 @@ public static class ScriptTrustValidator
    {
        private readonly SortedSet<string> _violations;

+        /// <summary>Initializes the walker with the shared violations set to write findings into.</summary>
+        /// <param name="violations">The dedup set shared with the semantic pass.</param>
        internal HardeningWalker(SortedSet<string> violations) => _violations = violations;

        /// <summary>
@@ -32,6 +32,7 @@ public sealed class TriggerCompileSurface
    public sealed class ReadOnlyAttributes
    {
        /// <summary>Mirrors <c>ReadOnlyAttributes.this[string]</c>.</summary>
+        /// <param name="key">The attribute name to look up.</param>
        public object? this[string key] => throw new NotSupportedException(CompileOnly);
    }

@@ -46,6 +47,7 @@ public sealed class TriggerCompileSurface
    public sealed class ReadOnlyChildren
    {
        /// <summary>Mirrors <c>ReadOnlyChildren.this[string]</c>.</summary>
+        /// <param name="compositionName">The composition name to look up.</param>
        public ReadOnlyComposition this[string compositionName] => throw new NotSupportedException(CompileOnly);
    }
 }