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
@@ -39,6 +39,7 @@ public class AttributeAccessor
    /// Resolves a key to its full canonical name by applying the scope prefix.
    /// </summary>
    /// <param name="key">The attribute key to resolve.</param>
+    /// <returns>The fully qualified canonical name (e.g. "TempSensor.X" or "X" for the root scope).</returns>
    public string Resolve(string key) =>
        ScopePrefix.Length == 0 ? key : ScopePrefix + "." + key;

@@ -59,6 +60,7 @@ public class AttributeAccessor
    /// Gets an attribute value asynchronously.
    /// </summary>
    /// <param name="key">The attribute key.</param>
+    /// <returns>A task that resolves to the attribute value, or null if not set.</returns>
    public Task<object?> GetAsync(string key) => _ctx.GetAttribute(Resolve(key));

    /// <summary>
@@ -66,6 +68,7 @@ public class AttributeAccessor
    /// </summary>
    /// <param name="key">The attribute key.</param>
    /// <param name="value">The value to set.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public Task SetAsync(string key, object? value)
        => _ctx.SetAttribute(Resolve(key), value?.ToString() ?? string.Empty);
 }
@@ -102,6 +105,7 @@ public class CompositionAccessor
    /// Resolves a script name to its full canonical name by applying the composition path.
    /// </summary>
    /// <param name="scriptName">The script name to resolve.</param>
+    /// <returns>The fully qualified canonical script name (e.g. "Module.MyScript" or "MyScript" at root).</returns>
    public string ResolveScript(string scriptName) =>
        Path.Length == 0 ? scriptName : Path + "." + scriptName;

@@ -110,6 +114,7 @@ public class CompositionAccessor
    /// </summary>
    /// <param name="scriptName">The name of the script to call.</param>
    /// <param name="parameters">Optional parameters to pass to the script.</param>
+    /// <returns>A task that resolves to the script's return value, or null if none.</returns>
    public Task<object?> CallScript(string scriptName, object? parameters = null)
        => _ctx.CallScript(ResolveScript(scriptName), parameters);
 }
@@ -157,6 +162,7 @@ internal static class ScopeAccessorFactory
    /// </summary>
    /// <param name="ctx">The script runtime context.</param>
    /// <param name="selfPath">The canonical-name path.</param>
+    /// <returns>A new <see cref="AttributeAccessor"/> rooted at <paramref name="selfPath"/>.</returns>
    public static AttributeAccessor AttributesFor(ScriptRuntimeContext ctx, string selfPath)
        => new(ctx, selfPath);

@@ -165,6 +171,7 @@ internal static class ScopeAccessorFactory
    /// </summary>
    /// <param name="ctx">The script runtime context.</param>
    /// <param name="selfPath">The canonical-name path.</param>
+    /// <returns>A new <see cref="ChildrenAccessor"/> rooted at <paramref name="selfPath"/>.</returns>
    public static ChildrenAccessor ChildrenFor(ScriptRuntimeContext ctx, string selfPath)
        => new(ctx, selfPath);

@@ -173,6 +180,7 @@ internal static class ScopeAccessorFactory
    /// </summary>
    /// <param name="ctx">The script runtime context.</param>
    /// <param name="parentPath">The parent path, or null if no parent.</param>
+    /// <returns>A <see cref="CompositionAccessor"/> for the parent, or null when <paramref name="parentPath"/> is null.</returns>
    public static CompositionAccessor? ParentFor(ScriptRuntimeContext ctx, string? parentPath)
        => parentPath == null ? null : new CompositionAccessor(ctx, parentPath);
 }
@@ -69,6 +69,7 @@ public class ScriptCompilationService
    /// Returns a list of violation messages, empty if clean.
    /// </summary>
    /// <param name="code">The script code to validate.</param>
+    /// <returns>A list of trust-model violation messages; empty if the script is clean.</returns>
    public IReadOnlyList<string> ValidateTrustModel(string code)
    {
        var tree = CSharpSyntaxTree.ParseText(
@@ -243,6 +244,7 @@ public class ScriptCompilationService
    /// </summary>
    /// <param name="scriptName">The name of the script.</param>
    /// <param name="code">The script code to compile.</param>
+    /// <returns>A <see cref="ScriptCompilationResult"/> containing the compiled script on success, or error messages on failure.</returns>
    public ScriptCompilationResult Compile(string scriptName, string code)
        => CompileCore(scriptName, code, typeof(ScriptGlobals));

@@ -255,6 +257,7 @@ public class ScriptCompilationService
    /// </summary>
    /// <param name="name">The name of the trigger expression.</param>
    /// <param name="expression">The trigger expression to compile.</param>
+    /// <returns>A <see cref="ScriptCompilationResult"/> containing the compiled expression on success, or error messages on failure.</returns>
    public ScriptCompilationResult CompileTriggerExpression(string name, string expression)
        => CompileCore(name, expression, typeof(TriggerExpressionGlobals));

@@ -327,11 +330,13 @@ public class ScriptCompilationResult

    /// <summary>Creates a successful compilation result.</summary>
    /// <param name="script">The compiled script.</param>
+    /// <returns>A <see cref="ScriptCompilationResult"/> with <see cref="IsSuccess"/> set to <c>true</c> and the compiled script attached.</returns>
    public static ScriptCompilationResult Succeeded(Script<object?> script) =>
        new(true, script, []);

    /// <summary>Creates a failed compilation result.</summary>
    /// <param name="errors">List of error messages.</param>
+    /// <returns>A <see cref="ScriptCompilationResult"/> with <see cref="IsSuccess"/> set to <c>false</c> and the provided error messages.</returns>
    public static ScriptCompilationResult Failed(IReadOnlyList<string> errors) =>
        new(false, null, errors);
 }
@@ -31,6 +31,7 @@ public sealed class ScriptExecutionScheduler : TaskScheduler, IDisposable
    /// first caller wins, subsequent calls reuse the existing instance.
    /// </summary>
    /// <param name="options">Site runtime options supplying the thread count for the scheduler.</param>
+    /// <returns>The process-wide <see cref="ScriptExecutionScheduler"/> instance, creating it on first call.</returns>
    public static ScriptExecutionScheduler Shared(SiteRuntimeOptions options)
    {
        if (_shared != null)
@@ -266,6 +266,7 @@ public class ScriptRuntimeContext
    /// </summary>
    /// <param name="attributeName">Name of the attribute to set.</param>
    /// <param name="value">String value to set for the attribute.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
    public async Task SetAttribute(string attributeName, string value)
    {
        var correlationId = Guid.NewGuid().ToString();
@@ -36,6 +36,7 @@ public class SharedScriptLibrary
    /// </summary>
    /// <param name="name">Unique name for the shared script.</param>
    /// <param name="code">C# source code of the shared script.</param>
+    /// <returns><c>true</c> if compilation succeeded and the script was registered; <c>false</c> if compilation failed.</returns>
    public bool CompileAndRegister(string name, string code)
    {
        var result = _compilationService.Compile(name, code);
@@ -60,6 +61,7 @@ public class SharedScriptLibrary
    /// Removes a shared script from the library.
    /// </summary>
    /// <param name="name">Name of the shared script to remove.</param>
+    /// <returns><c>true</c> if the script was found and removed; <c>false</c> if no script with that name was registered.</returns>
    public bool Remove(string name)
    {
        lock (_lock)
@@ -76,6 +78,7 @@ public class SharedScriptLibrary
    /// <param name="context">Runtime context providing instance state and services to the script globals.</param>
    /// <param name="parameters">Optional input parameters passed to the script.</param>
    /// <param name="cancellationToken">Cancellation token for the execution.</param>
+    /// <returns>A task that resolves to the script's return value, or <c>null</c> if the script returns nothing.</returns>
    public async Task<object?> ExecuteAsync(
        string scriptName,
        ScriptRuntimeContext context,
@@ -106,6 +109,7 @@ public class SharedScriptLibrary
    /// <summary>
    /// Returns the names of all currently registered shared scripts.
    /// </summary>
+    /// <returns>A snapshot list of all registered script names at the time of the call.</returns>
    public IReadOnlyList<string> GetRegisteredScriptNames()
    {
        lock (_lock)
@@ -118,6 +122,7 @@ public class SharedScriptLibrary
    /// Returns whether a script with the given name is registered.
    /// </summary>
    /// <param name="name">Name of the shared script to look up.</param>
+    /// <returns><c>true</c> if a script with the given name is registered; otherwise <c>false</c>.</returns>
    public bool Contains(string name)
    {
        lock (_lock)
@@ -20,6 +20,7 @@ public sealed class TriggerExpressionGlobals
    /// and AlarmActor.
    /// </summary>
    /// <param name="triggerConfigJson">JSON string of the trigger configuration, or null.</param>
+    /// <returns>The expression string, or <c>null</c> if the config is missing, blank, or malformed.</returns>
    public static string? ExtractExpression(string? triggerConfigJson)
    {
        if (string.IsNullOrEmpty(triggerConfigJson)) return null;