docs: fix and clarify XML comments

src/Ramstack.HtmxToolkit/Configuration/HtmxFetchMode.cs

@@ -6,9 +6,9 @@ namespace Ramstack.HtmxToolkit.Configuration;
 /// <remarks>
 /// <para>In HTMX 4.x this is passed as the <c>mode</c> option of the Fetch API.</para>
 /// <para>
-///   In HTMX 1.x and 2.x, the equivalent setting is the <c>selfRequestsOnly</c>
-///   boolean configuration option, for which <see cref="SameOrigin" /> corresponds to
-///   <see langword="true" /> and any other value corresponds to <see langword="false" />.
+///   HTMX 1.x and 2.x use <c>XMLHttpRequest</c> instead of <c>fetch</c>.
+///   Use <see cref="HtmxV1Config.SelfRequestsOnly" /> or <see cref="HtmxV2Config.SelfRequestsOnly" />
+///   to restrict requests to the current origin.
 /// </para>
 /// </remarks>
 public enum HtmxFetchMode

src/Ramstack.HtmxToolkit/Configuration/HtmxHistoryMode.cs

@@ -10,7 +10,7 @@ public enum HtmxHistoryMode
     /// </summary>
     /// <remarks>
     /// In HTMX 4.x, history navigation requests the URL from the server and swaps
-    /// the response. Local DOM snapshots require the optional HTMX history-cache extension.
+    /// the response. Local DOM snapshots require the optional HTMX <c>hx-history-cache</c> extension.
     /// </remarks>
     Enabled,
 

src/Ramstack.HtmxToolkit/Configuration/HtmxScrollBehavior.cs

@@ -1,7 +1,7 @@
 namespace Ramstack.HtmxToolkit.Configuration;
 
 /// <summary>
-/// Specifies the scrolling behavior for a boosted link during page transitions.
+/// Specifies how HTMX scrolls elements into view with the <c>show</c> swap modifier.
 /// </summary>
 public enum HtmxScrollBehavior
 {
@@ -17,7 +17,6 @@ public enum HtmxScrollBehavior
 
     /// <summary>
     /// Uses the <c>instant</c> scrolling behavior.
-    /// Supported only in HTMX 2.x.
     /// </summary>
     Instant
 }

src/Ramstack.HtmxToolkit/Configuration/HtmxV1Config.cs

@@ -143,7 +143,7 @@ public bool? AllowEval
     }
 
     /// <summary>
-    /// Gets or sets a value indicating whether script tags should be processed in new content.
+    /// Gets or sets a value indicating whether <c>&lt;script&gt;</c> tags should be processed in new content.
     /// The HTMX default is <see langword="true" />.
     /// </summary>
     public bool? AllowScriptTags
@@ -173,7 +173,7 @@ public string[]? AttributesToSettle
     }
 
     /// <summary>
-    /// Gets or sets a value indicating whether HTML template tags are used to parse content.
+    /// Gets or sets a value indicating whether HTML <c>&lt;template&gt;</c> tags are used to parse content.
     /// The HTMX default is <see langword="false" />.
     /// </summary>
     public bool? UseTemplateFragments
@@ -244,7 +244,7 @@ public bool? SelfRequestsOnly
     }
 
     /// <summary>
-    /// Gets or sets the scrolling behavior for boosted links.
+    /// Gets or sets the scrolling behavior used by the <c>show</c> modifier of <c>hx-swap</c>.
     /// The HTMX default is <see cref="HtmxScrollBehavior.Smooth" />.
     /// </summary>
     [JsonConverter(typeof(HtmxScrollBehaviorJsonConverter))]
@@ -265,7 +265,7 @@ public bool? DefaultFocusScroll
     }
 
     /// <summary>
-    /// Gets or sets a value indicating whether GET requests use a cache-busting parameter.
+    /// Gets or sets a value indicating whether <c>GET</c> requests use a cache-busting parameter.
     /// The HTMX default is <see langword="false" />.
     /// </summary>
     public bool? GetCacheBusterParam

src/Ramstack.HtmxToolkit/Configuration/HtmxV2Config.cs

@@ -143,7 +143,7 @@ public bool? AllowEval
     }
 
     /// <summary>
-    /// Gets or sets a value indicating whether script tags should be processed in new content.
+    /// Gets or sets a value indicating whether <c>&lt;script&gt;</c> tags should be processed in new content.
     /// The HTMX default is <see langword="true" />.
     /// </summary>
     public bool? AllowScriptTags
@@ -186,6 +186,7 @@ public string[]? AttributesToSettle
     /// Gets or sets the WebSocket reconnection delay strategy.
     /// The HTMX default is <c>full-jitter</c>.
     /// </summary>
+    /// <remarks>Requires the HTMX WebSocket extension.</remarks>
     public string? WsReconnectDelay
     {
         get;
@@ -196,6 +197,7 @@ public string? WsReconnectDelay
     /// Gets or sets the type of binary data received over WebSocket connections.
     /// The HTMX default is <see cref="HtmxBinaryType.Blob" />.
     /// </summary>
+    /// <remarks>Requires the HTMX WebSocket extension.</remarks>
     [JsonConverter(typeof(HtmxBinaryTypeJsonConverter))]
     public HtmxBinaryType? WsBinaryType
     {
@@ -254,7 +256,7 @@ public bool? SelfRequestsOnly
     }
 
     /// <summary>
-    /// Gets or sets the scrolling behavior for boosted links.
+    /// Gets or sets the scrolling behavior used by the <c>show</c> modifier of <c>hx-swap</c>.
     /// The HTMX default is <see cref="HtmxScrollBehavior.Instant" />.
     /// </summary>
     [JsonConverter(typeof(HtmxScrollBehaviorJsonConverter))]
@@ -275,7 +277,7 @@ public bool? DefaultFocusScroll
     }
 
     /// <summary>
-    /// Gets or sets a value indicating whether GET requests use a cache-busting parameter.
+    /// Gets or sets a value indicating whether <c>GET</c> requests use a cache-busting parameter.
     /// The HTMX default is <see langword="false" />.
     /// </summary>
     public bool? GetCacheBusterParam
@@ -362,6 +364,7 @@ public bool? AllowNestedOobSwaps
     /// as HTMX requests.
     /// The HTMX default is <see langword="true" />.
     /// </summary>
+    /// <remarks>Available since HTMX 2.0.5.</remarks>
     public bool? HistoryRestoreAsHxRequest
     {
         get;
@@ -373,6 +376,7 @@ public bool? HistoryRestoreAsHxRequest
     /// a request is issued.
     /// The HTMX default is <see langword="false" />.
     /// </summary>
+    /// <remarks>Available since HTMX 2.0.7.</remarks>
     public bool? ReportValidityOfForms
     {
         get;

src/Ramstack.HtmxToolkit/Configuration/HtmxV4Config.cs

@@ -54,11 +54,14 @@ public HtmxSwap? DefaultSwap
 
     /// <summary>
     /// Gets or sets a value indicating whether the main swap is performed
-    /// when the response contained only out-of-band elements.
-    /// <c>&lt;hx-partial&gt;</c> content always prevents the main swap.
-    /// The HTMX default is <see langword="false" /> and can be overridden
-    /// using the <c>swapEmpty</c> modifier on <c>hx-swap</c>.
+    /// when no content remains after processing out-of-band elements.
+    /// The HTMX default is <see langword="false" />.
     /// </summary>
+    /// <remarks>
+    /// Processed <c>&lt;hx-partial&gt;</c> elements suppress an empty main swap regardless
+    /// of this setting. The <c>swapEmpty</c> modifier on <c>hx-swap</c> overrides either default.
+    /// Nonempty main content is still swapped, and the <see cref="HtmxSwap.Delete" /> swap style always runs.
+    /// </remarks>
     [JsonPropertyName("allowEmptySwapAfterOOB")]
     public bool? AllowEmptySwapAfterOob
     {
@@ -149,7 +152,7 @@ public int? DefaultTimeout
 
     /// <summary>
     /// Gets or sets the request mode passed to the Fetch API.
-    /// The HTMX default is <c>same-origin</c>.
+    /// The HTMX default is <see cref="HtmxFetchMode.SameOrigin" />.
     /// </summary>
     [JsonConverter(typeof(HtmxFetchModeJsonConverter))]
     public HtmxFetchMode? Mode

src/Ramstack.HtmxToolkit/Configuration/HttpVerb.cs

@@ -6,52 +6,52 @@ namespace Ramstack.HtmxToolkit.Configuration;
 public enum HttpVerb
 {
     /// <summary>
-    /// The GET method requests a representation of the specified resource.
+    /// The <c>GET</c> method requests a representation of the specified resource.
     /// </summary>
     Get,
 
     /// <summary>
-    /// The HEAD method requests a response identical to a GET response,
+    /// The <c>HEAD</c> method requests a response identical to a <c>GET</c> response,
     /// but without the response body.
     /// </summary>
     Head,
 
     /// <summary>
-    /// The POST method submits an entity to the specified resource.
+    /// The <c>POST</c> method submits an entity to the specified resource.
     /// </summary>
     Post,
 
     /// <summary>
-    /// The PUT method replaces all current representations of the target resource
+    /// The <c>PUT</c> method replaces all current representations of the target resource
     /// with the request payload.
     /// </summary>
     Put,
 
     /// <summary>
-    /// The DELETE method deletes the specified resource.
+    /// The <c>DELETE</c> method deletes the specified resource.
     /// </summary>
     Delete,
 
     /// <summary>
-    /// The CONNECT method establishes a tunnel to the server
+    /// The <c>CONNECT</c> method establishes a tunnel to the server
     /// identified by the target resource.
     /// </summary>
     Connect,
 
     /// <summary>
-    /// The OPTIONS method describes the communication options
+    /// The <c>OPTIONS</c> method describes the communication options
     /// for the target resource.
     /// </summary>
     Options,
 
     /// <summary>
-    /// The TRACE method performs a message loop-back test
+    /// The <c>TRACE</c> method performs a message loop-back test
     /// along the path to the target resource.
     /// </summary>
     Trace,
 
     /// <summary>
-    /// The PATCH method applies partial modifications to a resource.
+    /// The <c>PATCH</c> method applies partial modifications to a resource.
     /// </summary>
     Patch
 }

src/Ramstack.HtmxToolkit/Configuration/ResponseHandlingConfig.cs

@@ -22,7 +22,7 @@ public sealed class ResponseHandlingConfig
     public bool? Error { get; set; }
 
     /// <summary>
-    /// Gets or sets a value indicating whether HTMX should ignore title tags in the response.
+    /// Gets or sets a value indicating whether HTMX should ignore <c>&lt;title&gt;</c> tags in the response.
     /// </summary>
     public bool? IgnoreTitle { get; set; }