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
@@ -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);
}