From 2a59f356d4f6e8a349a0192b04700b925b408f9b Mon Sep 17 00:00:00 2001
From: Mitch Denny <midenn@microsoft.com>
Date: Fri, 4 Oct 2024 14:12:56 +1000
Subject: [PATCH] Docs to cover 6006.

---
 .../ResourceBuilderExtensions.cs              | 24 ++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/src/Aspire.Hosting/ResourceBuilderExtensions.cs b/src/Aspire.Hosting/ResourceBuilderExtensions.cs
index 3d4db84b349..5e7f2e2ac76 100644
--- a/src/Aspire.Hosting/ResourceBuilderExtensions.cs
+++ b/src/Aspire.Hosting/ResourceBuilderExtensions.cs
@@ -398,7 +398,29 @@ private static void ApplyEndpoints<T>(this IResourceBuilder<T> builder, IResourc
     /// <param name="endpointName">Name of endpoint to change.</param>
     /// <param name="callback">Callback that modifies the endpoint.</param>
     /// <param name="createIfNotExists">Create endpoint if it does not exist.</param>
-    /// <returns></returns>
+    /// <returns>The resource builder</returns>
+    /// <remarks>
+    /// <para>
+    /// The <see cref="WithEndpoint{T}(IResourceBuilder{T}, string, Action{EndpointAnnotation}, bool)"/> method allows
+    /// developers to mutate any aspect of an endpoint annotation. Note that changing one value does not automatically change
+    /// other values to compatable/consistent values. For example setting the <see cref="EndpointAnnotation.Protocol"/> property
+    /// of the endpoint annotation in the callback will not automatically change the <see cref="EndpointAnnotation.UriScheme"/>.
+    /// All values should be set in the callback if the defaults are not acceptable.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// Configure an endpoint to use UDP.
+    /// <code lang="C#">
+    /// var builder = DistributedApplication.Create(args);
+    /// var container = builder.AddContainer("mycontainer", "myimage")
+    ///                        .WithEndpoint("myendpoint", e => {
+    ///                          e.Port = 9998;
+    ///                          e.TargetPort = 9999;
+    ///                          e.Protocol = ProtocolType.Udp;
+    ///                          e.UriScheme = "udp";
+    ///                        });
+    /// </code>
+    /// </example>
     [System.Diagnostics.CodeAnalysis.SuppressMessage("ApiDesign", "RS0026:Do not add multiple public overloads with optional parameters", Justification = "<Pending>")]
     public static IResourceBuilder<T> WithEndpoint<T>(this IResourceBuilder<T> builder, [EndpointName] string endpointName, Action<EndpointAnnotation> callback, bool createIfNotExists = true) where T : IResourceWithEndpoints
     {