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
@@ -59,6 +59,7 @@ internal static class CSharpDelimiterScanner
    /// </summary>
    /// <param name="code">The C# source code to scan.</param>
    /// <param name="pattern">The substring to search for in code regions only.</param>
+    /// <returns><c>true</c> if <paramref name="pattern"/> occurs in a code region (not inside a comment, string, or char literal); otherwise <c>false</c>.</returns>
    internal static bool ContainsInCode(string code, string pattern)
    {
        if (string.IsNullOrEmpty(pattern))
@@ -162,6 +163,7 @@ internal static class CSharpDelimiterScanner
    /// ignored.
    /// </summary>
    /// <param name="code">The C# source code to scan for delimiter balance.</param>
+    /// <returns>The first <see cref="Mismatch"/> found, or <see cref="Mismatch.None"/> if all delimiters are balanced.</returns>
    internal static Mismatch Scan(string code)
    {
        int brace = 0, bracket = 0, paren = 0;
@@ -25,6 +25,8 @@ public class SemanticValidator
    /// </summary>
    /// <param name="configuration">The flattened configuration to validate.</param>
    /// <param name="sharedScripts">Shared scripts available for CallShared references.</param>
+    /// <param name="alarmCapableConnectionNames">Connection names that support alarm subscriptions; used to validate native alarm source bindings.</param>
+    /// <returns>A <see cref="ValidationResult"/> containing all semantic errors and warnings found.</returns>
    public ValidationResult Validate(
        FlattenedConfiguration configuration,
        IReadOnlyList<ResolvedScript>? sharedScripts = null,
@@ -288,6 +290,7 @@ public class SemanticValidator
    /// Parses a parameter definitions JSON string (JSON Schema or legacy flat array) and returns the declared parameter names.
    /// </summary>
    /// <param name="parameterDefinitionsJson">JSON Schema or legacy flat-array string; null/empty returns an empty list.</param>
+    /// <returns>The list of parameter names declared in the definition.</returns>
    internal static List<string> ParseParameterDefinitions(string? parameterDefinitionsJson)
    {
        if (string.IsNullOrWhiteSpace(parameterDefinitionsJson))
@@ -325,6 +328,7 @@ public class SemanticValidator
    /// Looks for CallScript("name", ...) and CallShared("name", ...) patterns.
    /// </summary>
    /// <param name="code">The script source code to scan.</param>
+    /// <returns>The list of call targets found (both <c>CallScript</c> and <c>CallShared</c> invocations).</returns>
    internal static List<CallTarget> ExtractCallTargets(string code)
    {
        var results = new List<CallTarget>();
@@ -45,6 +45,7 @@ public class ValidationService
    /// </summary>
    /// <param name="configuration">The flattened configuration to validate.</param>
    /// <param name="sharedScripts">Optional list of shared scripts for validation context.</param>
+    /// <returns>A merged <see cref="ValidationResult"/> aggregating all pipeline stage outcomes.</returns>
    public ValidationResult Validate(FlattenedConfiguration configuration, IReadOnlyList<ResolvedScript>? sharedScripts = null)
    {
        ArgumentNullException.ThrowIfNull(configuration);
@@ -68,6 +69,7 @@ public class ValidationService
    /// Validates that flattening produced a non-empty configuration.
    /// </summary>
    /// <param name="configuration">The flattened configuration to validate.</param>
+    /// <returns>A <see cref="ValidationResult"/> with errors or warnings if the configuration is empty or missing a name; otherwise success.</returns>
    public static ValidationResult ValidateFlatteningSuccess(FlattenedConfiguration configuration)
    {
        var errors = new List<ValidationEntry>();
@@ -97,6 +99,7 @@ public class ValidationService
    /// Canonical names must be unique within their entity type (attributes, alarms, scripts).
    /// </summary>
    /// <param name="configuration">The flattened configuration to validate.</param>
+    /// <returns>A <see cref="ValidationResult"/> with errors for each duplicate canonical name, or success.</returns>
    public static ValidationResult ValidateNamingCollisions(FlattenedConfiguration configuration)
    {
        var errors = new List<ValidationEntry>();
@@ -114,6 +117,7 @@ public class ValidationService
    /// Validates that all scripts compile successfully using the ScriptCompiler.
    /// </summary>
    /// <param name="configuration">The flattened configuration to validate.</param>
+    /// <returns>A <see cref="ValidationResult"/> with errors for each script that fails compilation.</returns>
    public ValidationResult ValidateScriptCompilation(FlattenedConfiguration configuration)
    {
        var errors = new List<ValidationEntry>();
@@ -138,6 +142,7 @@ public class ValidationService
    /// Alarm trigger configs are JSON with an "attributeName" field referencing a canonical attribute name.
    /// </summary>
    /// <param name="configuration">The flattened configuration to validate.</param>
+    /// <returns>A <see cref="ValidationResult"/> with errors for any alarm whose trigger references a missing attribute.</returns>
    public static ValidationResult ValidateAlarmTriggerReferences(FlattenedConfiguration configuration)
    {
        var errors = new List<ValidationEntry>();
@@ -167,6 +172,7 @@ public class ValidationService
    /// Validates that script trigger configurations reference existing attributes.
    /// </summary>
    /// <param name="configuration">The flattened configuration to validate.</param>
+    /// <returns>A <see cref="ValidationResult"/> with errors for any script whose trigger references a missing attribute.</returns>
    public static ValidationResult ValidateScriptTriggerReferences(FlattenedConfiguration configuration)
    {
        var errors = new List<ValidationEntry>();
@@ -209,6 +215,7 @@ public class ValidationService
    /// </list>
    /// </summary>
    /// <param name="configuration">The flattened configuration to validate.</param>
+    /// <returns>A <see cref="ValidationResult"/> with errors and warnings from all expression trigger checks.</returns>
    public static ValidationResult ValidateExpressionTriggers(FlattenedConfiguration configuration)
    {
        var errors = new List<ValidationEntry>();
@@ -302,6 +309,7 @@ public class ValidationService
    /// configuration. Returns <c>null</c> on malformed JSON or a missing key.
    /// </summary>
    /// <param name="triggerConfigJson">The trigger configuration JSON to parse.</param>
+    /// <returns>The expression string, or <c>null</c> if absent or the JSON is malformed.</returns>
    internal static string? ExtractExpressionFromTriggerConfig(string? triggerConfigJson)
    {
        if (string.IsNullOrWhiteSpace(triggerConfigJson))
@@ -330,6 +338,7 @@ public class ValidationService
    /// looks well-formed.
    /// </summary>
    /// <param name="expression">The expression to check for syntax errors.</param>
+    /// <returns>A human-readable error message if the expression is invalid; <c>null</c> if well-formed.</returns>
    internal static string? CheckExpressionSyntax(string expression)
    {
        // Advisory forbidden-API scan (TemplateEngine-006): code-region-aware so
@@ -439,6 +448,7 @@ public class ValidationService
    /// and skips keys built dynamically.
    /// </summary>
    /// <param name="expression">The expression to scan for attribute references.</param>
+    /// <returns>The distinct attribute key strings found in self-attribute accessor positions.</returns>
    internal static IEnumerable<string> ExtractAttributeReferences(string expression)
    {
        var seen = new HashSet<string>(StringComparer.Ordinal);
@@ -490,6 +500,7 @@ public class ValidationService
    /// Validates that all data-sourced attributes have connection bindings.
    /// </summary>
    /// <param name="configuration">The flattened configuration to validate.</param>
+    /// <returns>A <see cref="ValidationResult"/> with warnings for each data-sourced attribute that lacks a connection binding.</returns>
    public static ValidationResult ValidateConnectionBindingCompleteness(FlattenedConfiguration configuration)
    {
        var errors = new List<ValidationEntry>();
@@ -531,6 +542,7 @@ public class ValidationService
    /// Extracts the attribute name from a trigger configuration JSON.
    /// </summary>
    /// <param name="triggerConfigJson">The trigger configuration JSON to parse.</param>
+    /// <returns>The attribute name from the <c>attributeName</c> or legacy <c>attribute</c> key, or <c>null</c> if absent or malformed.</returns>
    internal static string? ExtractAttributeNameFromTriggerConfig(string triggerConfigJson)
    {
        // Accept both keys to stay consistent with FlatteningService.PrefixTriggerAttribute,
@@ -558,6 +570,7 @@ public class ValidationService
    /// validate" and let other checks surface the deeper problem.
    /// </summary>
    /// <param name="triggerConfigJson">The trigger configuration JSON to parse.</param>
+    /// <returns>A <see cref="HiLoSetpoints"/> record with the parsed setpoint values; any missing or non-numeric value is <c>null</c>.</returns>
    internal static HiLoSetpoints ExtractHiLoSetpoints(string triggerConfigJson)
    {
        try