[release/9.1] Improve XML documentation comments (#7737)

* Improved XML doc comments.

* Update src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs

Co-authored-by: Dan Moseley <[email protected]>

* Update src/Aspire.Hosting/ResourceBuilderExtensions.cs

Co-authored-by: James Newton-King <[email protected]>

* Update src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs

Co-authored-by: James Newton-King <[email protected]>

* Update src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs

Co-authored-by: James Newton-King <[email protected]>

* Update src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs

Co-authored-by: James Newton-King <[email protected]>

* Update src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs

Co-authored-by: Eric Erhardt <[email protected]>

* Update src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs

Co-authored-by: Eric Erhardt <[email protected]>

* Update src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs

Co-authored-by: Eric Erhardt <[email protected]>

* Remove unncessary sentence.

---------

Co-authored-by: Mitch Denny <[email protected]>
Co-authored-by: Dan Moseley <[email protected]>
Co-authored-by: James Newton-King <[email protected]>
Co-authored-by: Eric Erhardt <[email protected]>

Author: 5 people

src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs

@@ -226,8 +226,17 @@ static bool IsContinuableState(WaitBehavior waitBehavior, CustomResourceSnapshot
     /// <param name="cancellationToken">The cancellation token.</param>
     /// <returns>A task.</returns>
     /// <remarks>
+    /// <para>
     /// This method returns a task that will complete with the resource is healthy. A resource
-    /// without <see cref="HealthCheckAnnotation"/> annotations will be considered healthy.
+    /// without <see cref="HealthCheckAnnotation"/> annotations will be considered healthy once
+    /// it reaches a <see cref="KnownResourceStates.Running"/> state.
+    /// </para>
+    /// <para>
+    /// If the resource enters an unavailable state such as <see cref="KnownResourceStates.FailedToStart"/> then
+    /// this method will continue to wait to enable scenarios where a resource could be restarted and recover. To
+    /// control this behavior use <see cref="WaitForResourceHealthyAsync(string, WaitBehavior, CancellationToken)"/>
+    /// or configure the default behavior with <see cref="ResourceNotificationServiceOptions.DefaultWaitBehavior"/>.
+    /// </para>
     /// </remarks>
     public async Task<ResourceEvent> WaitForResourceHealthyAsync(string resourceName, CancellationToken cancellationToken = default)
     {
@@ -245,8 +254,22 @@ public async Task<ResourceEvent> WaitForResourceHealthyAsync(string resourceName
     /// <param name="waitBehavior">The wait behavior.</param>
     /// <returns>A task.</returns>
     /// <remarks>
+    /// <para>
     /// This method returns a task that will complete with the resource is healthy. A resource
-    /// without <see cref="HealthCheckAnnotation"/> annotations will be considered healthy.
+    /// without <see cref="HealthCheckAnnotation"/> annotations will be considered healthy once
+    /// it reaches a <see cref="KnownResourceStates.Running"/> state. The
+    /// <see cref="WaitBehavior"/> controls how the wait operation behaves when the resource
+    /// enters an unavailable state such as <see cref="KnownResourceStates.FailedToStart"/>.
+    /// </para>
+    /// <para>
+    /// When <see cref="WaitBehavior.WaitOnResourceUnavailable"/> is specified the wait operation
+    /// will continue to wait until the resource reaches a <see cref="KnownResourceStates.Running"/> state.
+    /// </para>
+    /// <para>
+    /// When <see cref="WaitBehavior.StopOnResourceUnavailable"/> is specified the wait operation
+    /// will throw a <see cref="DistributedApplicationException"/> if the resource enters an
+    /// unavailable state.
+    /// </para>
     /// </remarks>
     public async Task<ResourceEvent> WaitForResourceHealthyAsync(string resourceName, WaitBehavior waitBehavior, CancellationToken cancellationToken = default)
     {

src/Aspire.Hosting/ResourceBuilderExtensions.cs

@@ -729,7 +729,12 @@ public static IResourceBuilder<T> WaitFor<T>(this IResourceBuilder<T> builder, I
     /// return <see cref="HealthStatus.Healthy"/>.</para>
     /// <para>The <see cref="WithHealthCheck{T}(IResourceBuilder{T}, string)"/> method can be used to associate
     /// additional health checks with a resource.</para>
-    /// <para>The <paramref name="waitBehavior"/> parameter can be used to control the behavior of the wait operation.</para>
+    /// <para>The <paramref name="waitBehavior"/> parameter can be used to control the behavior of the
+    /// wait operation. When <see cref="WaitBehavior.WaitOnResourceUnavailable"/> is specified, the wait
+    /// operation will continue to wait until the resource becomes healthy. This is the default
+    /// behavior with the <see cref="WaitFor{T}(IResourceBuilder{T}, IResourceBuilder{IResource})"/> overload.</para>
+    /// <para>When <see cref="WaitBehavior.StopOnResourceUnavailable"/> is specified, the wait operation
+    /// will throw a <see cref="DistributedApplicationException"/> if the resource enters an unavailable state.</para>
     /// </remarks>
     /// <example>
     /// Start message queue before starting the worker service.