Documentation modifications

adas-core.Domain/Utils/RelayHelper.cs

@@ -10,6 +10,12 @@ namespace adas_core.Domain.Utils;
 /// </summary>
 public class RelayHelper
 {
+    /// <summary>
+    /// Retrieves the current status of a <see cref="Relay"/> by calling a local REST API endpoint built from its connection parameters, returning <see langword="true"/> when the relay is reported as active and <see langword="false"/> when the response is not <see cref="HttpStatusCode.OK"/>, the payload cannot be converted to a boolean, or any exception is raised during the request.
+    /// </summary>
+    /// <param name="relay">The <see cref="Relay"/> whose status is queried; its <see cref="Relay.RelayNumber"/> is used in the URL path while <see cref="Relay.Driver"/>, <see cref="Relay.Ip"/>, and <see cref="Relay.Port"/> are passed as query parameters.</param>
+    /// <returns><see langword="true"/> if the API responds with <see cref="HttpStatusCode.OK"/> and the response body converts to a boolean value of <see langword="true"/>; otherwise, <see langword="false"/>.</returns>
+    /// <!-- aidoc:v1 sig=0240829 body=a1db00d -->
     public static bool GetRelayStatusFromApiRest(Relay relay)
     {
         UriBuilder builder = new()
@@ -94,6 +100,12 @@ public class RelayHelper
             PowerRelay(relay, builder);
         }
 
+    /// <summary>
+    /// Sends an HTTP POST request to power a <see cref="Relay"/> through the endpoint described by <paramref name="builder"/>, enriching the query string with the relay's driver, IP address, port, and a fixed channel count of 8. Logs an information message when the response status is not <see cref="HttpStatusCode.OK"/> and logs any exception raised during the call at debug level instead of propagating it.
+    /// </summary>
+    /// <param name="relay">The relay to power, whose <see cref="Relay.Driver"/>, <see cref="Relay.Ip"/> and <see cref="Relay.Port"/> values are written into the request query string.</param>
+    /// <param name="builder">The <see cref="UriBuilder"/> whose query string is populated and whose <see cref="UriBuilder.Uri"/> identifies the target endpoint of the POST request.</param>
+    /// <!-- aidoc:v1 sig=01d6944 body=089ce17 -->
     private static void PowerRelay(Relay relay, UriBuilder builder)
     {
         var query = HttpUtility.ParseQueryString(builder.Query);