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.

src/ZB.MOM.WW.ScadaBridge.CentralUI/ScriptAnalysis/ISharedScriptCatalog.cs

@@ -9,6 +9,7 @@ namespace ZB.MOM.WW.ScadaBridge.CentralUI.ScriptAnalysis;
 public interface ISharedScriptCatalog
 {
     /// <summary>Returns the parameter and return shapes for all registered shared scripts.</summary>
+    /// <returns>A task that resolves to the list of all shared script shapes.</returns>
     Task<IReadOnlyList<ScriptShape>> GetShapesAsync();
 
     /// <summary>
@@ -18,6 +19,7 @@ public interface ISharedScriptCatalog
     /// </summary>
     /// <param name="name">Name of the shared script to retrieve.</param>
     /// <param name="cancellationToken">Cancellation token for the async lookup.</param>
+    /// <returns>A task that resolves to the matching shared script source, or null if none exists.</returns>
     Task<SharedScriptSource?> GetByNameAsync(string name, CancellationToken cancellationToken = default);
 }
 

src/ZB.MOM.WW.ScadaBridge.CentralUI/ScriptAnalysis/InboundScriptHost.cs

@@ -32,6 +32,7 @@ public class InboundScriptHost
         /// Targets a specific instance for method invocation.
         /// </summary>
         /// <param name="instanceCode">The instance code to target.</param>
+        /// <returns>A <see cref="RouteTarget"/> scoped to the specified instance.</returns>
         public RouteTarget To(string instanceCode) => new();
     }
 
@@ -44,6 +45,7 @@ public class InboundScriptHost
         /// <param name="scriptName">The name of the script to call.</param>
         /// <param name="parameters">Optional parameters to pass to the script.</param>
         /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns>A task that resolves to the script's return value, or null.</returns>
         public System.Threading.Tasks.Task<object?> Call(
             string scriptName,
             object? parameters = null,
@@ -55,6 +57,7 @@ public class InboundScriptHost
         /// </summary>
         /// <param name="attributeName">The name of the attribute to retrieve.</param>
         /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns>A task that resolves to the attribute value, or null if not found.</returns>
         public System.Threading.Tasks.Task<object?> GetAttribute(
             string attributeName,
             System.Threading.CancellationToken cancellationToken = default) =>
@@ -65,6 +68,7 @@ public class InboundScriptHost
         /// </summary>
         /// <param name="attributeNames">The names of the attributes to retrieve.</param>
         /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns>A task that resolves to a dictionary mapping attribute names to their values.</returns>
         public System.Threading.Tasks.Task<IReadOnlyDictionary<string, object?>> GetAttributes(
             IEnumerable<string> attributeNames,
             System.Threading.CancellationToken cancellationToken = default) =>
@@ -77,6 +81,7 @@ public class InboundScriptHost
         /// <param name="attributeName">The name of the attribute to set.</param>
         /// <param name="value">The value to set.</param>
         /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns>A task representing the asynchronous operation.</returns>
         public System.Threading.Tasks.Task SetAttribute(
             string attributeName,
             string value,
@@ -88,6 +93,7 @@ public class InboundScriptHost
         /// </summary>
         /// <param name="attributeValues">Dictionary of attribute names to values.</param>
         /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns>A task representing the asynchronous operation.</returns>
         public System.Threading.Tasks.Task SetAttributes(
             IReadOnlyDictionary<string, string> attributeValues,
             System.Threading.CancellationToken cancellationToken = default) =>

src/ZB.MOM.WW.ScadaBridge.CentralUI/ScriptAnalysis/JsonSchemaShapeParser.cs

@@ -20,6 +20,7 @@ public static class JsonSchemaShapeParser
 {
     /// <summary>Parses a JSON Schema or legacy flat-array parameters definition and returns the resulting parameter shapes.</summary>
     /// <param name="json">The JSON string to parse; <c>null</c> or whitespace returns an empty list.</param>
+    /// <returns>A read-only list of <see cref="ParameterShape"/> instances parsed from the definition; empty on null, whitespace, or malformed input.</returns>
     public static IReadOnlyList<ParameterShape> ParseParameters(string? json)
     {
         if (string.IsNullOrWhiteSpace(json)) return Array.Empty<ParameterShape>();
@@ -41,6 +42,7 @@ public static class JsonSchemaShapeParser
 
     /// <summary>Parses a JSON Schema or legacy return-type definition and returns the normalised type name, or <c>null</c> if absent or unrecognised.</summary>
     /// <param name="json">The JSON string to parse; <c>null</c> or whitespace returns <c>null</c>.</param>
+    /// <returns>The normalised type name string (e.g. <c>"Boolean"</c>, <c>"List&lt;Integer&gt;"</c>), or <c>null</c> if the input is null, whitespace, malformed, or unrecognised.</returns>
     public static string? ParseReturnType(string? json)
     {
         if (string.IsNullOrWhiteSpace(json)) return null;

src/ZB.MOM.WW.ScadaBridge.CentralUI/ScriptAnalysis/SandboxConsoleCapture.cs

@@ -41,6 +41,7 @@ internal sealed class SandboxConsoleCapture : TextWriter
     /// <see cref="Console.Error"/> once for the process. Idempotent and
     /// thread-safe. Subsequent calls return the already-installed instances.
     /// </summary>
+    /// <returns>The installed <see cref="SandboxConsoleCapture"/> instances for stdout and stderr.</returns>
     public static (SandboxConsoleCapture Out, SandboxConsoleCapture Error) Install()
     {
         if (_outInstance != null && _errorInstance != null)
@@ -72,6 +73,7 @@ internal sealed class SandboxConsoleCapture : TextWriter
     /// other call-trees are unaffected.
     /// </summary>
     /// <param name="buffer">The writer that receives console output for this scope.</param>
+    /// <returns>A <see cref="CaptureScope"/> that, when disposed, restores the previous capture state.</returns>
     public CaptureScope BeginCapture(StringWriter buffer)
     {
         var previous = _current.Value;

src/ZB.MOM.WW.ScadaBridge.CentralUI/ScriptAnalysis/SandboxHostHelpers.cs

@@ -32,6 +32,7 @@ public class SandboxExternalHelper
     /// <param name="methodName">The method name to invoke.</param>
     /// <param name="parameters">Optional method parameters.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to the <see cref="ExternalCallResult"/> from the external system.</returns>
     public Task<ExternalCallResult> Call(
         string systemName,
         string methodName,
@@ -49,6 +50,7 @@ public class SandboxExternalHelper
     /// <param name="methodName">The method name to invoke.</param>
     /// <param name="parameters">Optional method parameters.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to the <see cref="ExternalCallResult"/> from the external system.</returns>
     public Task<ExternalCallResult> CachedCall(
         string systemName,
         string methodName,
@@ -80,6 +82,7 @@ public class SandboxDatabaseHelper
     /// <summary>Gets a database connection by name.</summary>
     /// <param name="name">The database connection name.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to the open <see cref="DbConnection"/> for the named database.</returns>
     public Task<DbConnection> Connection(string name, CancellationToken cancellationToken = default)
     {
         if (_gateway == null)
@@ -93,6 +96,7 @@ public class SandboxDatabaseHelper
     /// <param name="sql">The SQL statement to execute.</param>
     /// <param name="parameters">Optional SQL parameters.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public Task CachedWrite(
         string name,
         string sql,
@@ -123,6 +127,7 @@ public class SandboxNotifyHelper
 {
     /// <summary>Selects the notification list to send to.</summary>
     /// <param name="listName">The notification list name.</param>
+    /// <returns>A <see cref="SandboxNotifyTarget"/> for the specified list.</returns>
     public SandboxNotifyTarget To(string listName) =>
         new();
 
@@ -133,6 +138,7 @@ public class SandboxNotifyHelper
     /// <c>NotifyHelper.Status</c>.
     /// </summary>
     /// <param name="notificationId">The notification ID to check status for.</param>
+    /// <returns>A task that resolves to a placeholder <see cref="NotificationDeliveryStatus"/> with status "Unknown".</returns>
     public Task<NotificationDeliveryStatus> Status(string notificationId) =>
         Task.FromResult(new NotificationDeliveryStatus("Unknown", 0, null, null));
 }
@@ -156,6 +162,7 @@ public class SandboxNotifyTarget
     /// <param name="subject">The notification subject.</param>
     /// <param name="message">The notification message.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to a fake notification ID string (a random GUID).</returns>
     public Task<string> Send(string subject, string message, CancellationToken cancellationToken = default) =>
         Task.FromResult(Guid.NewGuid().ToString("N"));
 }

src/ZB.MOM.WW.ScadaBridge.CentralUI/ScriptAnalysis/SandboxInboundScriptHost.cs

@@ -30,6 +30,7 @@ public class SandboxInboundScriptHost
         /// Creates a sandbox route target that throws on every operation.
         /// </summary>
         /// <param name="instanceCode">The instance code (used only in the exception message).</param>
+        /// <returns>A sandbox route target bound to <paramref name="instanceCode"/>.</returns>
         public RouteTarget To(string instanceCode) => new(instanceCode);
     }
 
@@ -50,6 +51,7 @@ public class SandboxInboundScriptHost
         /// <param name="scriptName">Script name (included in the exception message).</param>
         /// <param name="parameters">Unused parameters.</param>
         /// <param name="cancellationToken">Unused token.</param>
+        /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/>.</returns>
         public Task<object?> Call(
             string scriptName,
             object? parameters = null,
@@ -61,6 +63,7 @@ public class SandboxInboundScriptHost
         /// </summary>
         /// <param name="attributeName">Attribute name (included in the exception message).</param>
         /// <param name="cancellationToken">Unused token.</param>
+        /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/>.</returns>
         public Task<object?> GetAttribute(
             string attributeName,
             CancellationToken cancellationToken = default) =>
@@ -71,6 +74,7 @@ public class SandboxInboundScriptHost
         /// </summary>
         /// <param name="attributeNames">Attribute names (unused).</param>
         /// <param name="cancellationToken">Unused token.</param>
+        /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/>.</returns>
         public Task<IReadOnlyDictionary<string, object?>> GetAttributes(
             IEnumerable<string> attributeNames,
             CancellationToken cancellationToken = default) =>
@@ -82,6 +86,7 @@ public class SandboxInboundScriptHost
         /// <param name="attributeName">Attribute name (included in the exception message).</param>
         /// <param name="value">Unused value.</param>
         /// <param name="cancellationToken">Unused token.</param>
+        /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/>.</returns>
         public Task SetAttribute(
             string attributeName,
             string value,
@@ -93,6 +98,7 @@ public class SandboxInboundScriptHost
         /// </summary>
         /// <param name="attributeValues">Unused attribute values.</param>
         /// <param name="cancellationToken">Unused token.</param>
+        /// <returns>Never returns; always throws <see cref="ScriptSandboxException"/>.</returns>
         public Task SetAttributes(
             IReadOnlyDictionary<string, string> attributeValues,
             CancellationToken cancellationToken = default) =>

src/ZB.MOM.WW.ScadaBridge.CentralUI/ScriptAnalysis/SandboxScriptHost.cs

@@ -102,6 +102,7 @@ public interface ISandboxInstanceGateway
     /// <param name="canonicalName">The canonical name of the attribute.</param>
     /// <param name="value">The value to set.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task SetAttributeAsync(string canonicalName, string value, CancellationToken ct);
 
     /// <summary>

src/ZB.MOM.WW.ScadaBridge.CentralUI/ScriptAnalysis/ScriptShapeParser.cs

@@ -12,6 +12,7 @@ public static class ScriptShapeParser
     /// <param name="name">The canonical script name.</param>
     /// <param name="parametersJson">The JSON Schema or legacy flat-array parameters definition, or <c>null</c> for parameterless scripts.</param>
     /// <param name="returnJson">The JSON Schema or legacy return-type definition, or <c>null</c> for void scripts.</param>
+    /// <returns>A <see cref="ScriptShape"/> describing the script's parameter list and return type.</returns>
     public static ScriptShape Parse(string name, string? parametersJson, string? returnJson)
     {
         var parameters = JsonSchemaShapeParser.ParseParameters(parametersJson);