From c04ea8b141a1a8944921ff0add9b65cb0e946ec8 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Tue, 3 Nov 2026 14:43:40 +0500
Subject: [PATCH] docs: correct and clarify XML comments and guides

---
 docs/articles/choosing-version.md             |  5 ++--
 docs/articles/responses.md                    |  2 ++
 .../Configuration/HtmxToolkitOptions.cs       | 24 +++++++++++++++++++
 .../HtmxResponseAttribute.cs                  |  2 +-
 .../TagHelpers/HtmxHeadersTagHelper.cs        |  8 +++----
 .../TagHelpers/HtmxRequestTagHelper.cs        |  8 +++----
 .../TagHelpers/HtmxValsTagHelper.cs           |  8 +++----
 7 files changed, 42 insertions(+), 15 deletions(-)

diff --git a/docs/articles/choosing-version.md b/docs/articles/choosing-version.md
index 98ab554..d552a38 100644
--- a/docs/articles/choosing-version.md
+++ b/docs/articles/choosing-version.md
@@ -30,8 +30,9 @@ builder.Services.AddHtmxToolkit(options =>
 });
 ```
 
-The version can be selected only once. Repeated configuration for the same version updates the same version-specific object;
-trying to select a different version causes startup validation to fail.
+Calling the same `UseHtmxV1`, `UseHtmxV2`, or `UseHtmxV4` method again reuses the existing version-specific
+configuration object and applies the supplied delegate. Calling a method for a different major version
+throws `InvalidOperationException`.
 
 > [!IMPORTANT]
 > Selecting a target version does not download or serve HTMX. The `<script>` loaded by the application must match the configured major version.
diff --git a/docs/articles/responses.md b/docs/articles/responses.md
index 8a4339c..bc354be 100644
--- a/docs/articles/responses.md
+++ b/docs/articles/responses.md
@@ -330,6 +330,8 @@ replaces the inherited one entirely.
 The attribute sets its headers before the action or page handler runs, so it works as a default.
 The code can replace a header with `Response.Htmx(...)` or remove it through `Response.GetHtmxHeaders()`,
 for example to retarget validation errors.
+Headers are not set if another filter short-circuits execution before this filter runs.
+If a later filter short-circuits execution, the headers have already been set.
 
 ## Access headers directly
 
diff --git a/src/Ramstack.HtmxToolkit/Configuration/HtmxToolkitOptions.cs b/src/Ramstack.HtmxToolkit/Configuration/HtmxToolkitOptions.cs
index dda7942..200685d 100644
--- a/src/Ramstack.HtmxToolkit/Configuration/HtmxToolkitOptions.cs
+++ b/src/Ramstack.HtmxToolkit/Configuration/HtmxToolkitOptions.cs
@@ -68,6 +68,14 @@ public HtmxConfig HtmxConfig
     /// <returns>
     /// The current options instance.
     /// </returns>
+    /// <remarks>
+    /// <para>
+    ///   Calling this method again reuses the existing configuration and applies the supplied delegate.
+    /// </para>
+    /// <para>
+    ///   Throws <see cref="InvalidOperationException" /> if a different HTMX major version has already been selected.
+    /// </para>
+    /// </remarks>
     [MemberNotNull(nameof(_config))]
     public HtmxToolkitOptions UseHtmxV1(Action<HtmxV1Config>? configure = null)
     {
@@ -83,6 +91,14 @@ public HtmxToolkitOptions UseHtmxV1(Action<HtmxV1Config>? configure = null)
     /// <returns>
     /// The current options instance.
     /// </returns>
+    /// <remarks>
+    /// <para>
+    ///   Calling this method again reuses the existing configuration and applies the supplied delegate.
+    /// </para>
+    /// <para>
+    ///   Throws <see cref="InvalidOperationException" /> if a different HTMX major version has already been selected.
+    /// </para>
+    /// </remarks>
     [MemberNotNull(nameof(_config))]
     public HtmxToolkitOptions UseHtmxV2(Action<HtmxV2Config>? configure = null)
     {
@@ -98,6 +114,14 @@ public HtmxToolkitOptions UseHtmxV2(Action<HtmxV2Config>? configure = null)
     /// <returns>
     /// The current options instance.
     /// </returns>
+    /// <remarks>
+    /// <para>
+    ///   Calling this method again reuses the existing configuration and applies the supplied delegate.
+    /// </para>
+    /// <para>
+    ///   Throws <see cref="InvalidOperationException" /> if a different HTMX major version has already been selected.
+    /// </para>
+    /// </remarks>
     [MemberNotNull(nameof(_config))]
     public HtmxToolkitOptions UseHtmxV4(Action<HtmxV4Config>? configure = null)
     {
diff --git a/src/Ramstack.HtmxToolkit/HtmxResponseAttribute.cs b/src/Ramstack.HtmxToolkit/HtmxResponseAttribute.cs
index 1d5479e..f2447c3 100644
--- a/src/Ramstack.HtmxToolkit/HtmxResponseAttribute.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxResponseAttribute.cs
@@ -18,7 +18,7 @@ namespace Ramstack.HtmxToolkit;
 ///   or an empty string, adds no header. Because the headers are set before the action or page handler runs,
 ///   the code can replace or remove them, for example with
 ///   <see cref="HttpResponseExtensions.Htmx(HttpResponse, Action{HtmxResponse})" />.
-///   If another filter short-circuits the action or page handler, the headers are not set.
+///   Headers are not set if another filter short-circuits execution before this filter runs.
 /// </para>
 /// <para>
 ///   The attribute can be applied to an action, a controller, or a Razor Pages page model.
diff --git a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxHeadersTagHelper.cs b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxHeadersTagHelper.cs
index 39f5d87..851929c 100644
--- a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxHeadersTagHelper.cs
+++ b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxHeadersTagHelper.cs
@@ -25,10 +25,10 @@ namespace Ramstack.HtmxToolkit.TagHelpers;
 ///   <item>In HTMX 4.x, the <c>append</c> modifier merges a child declaration into inherited headers.</item>
 /// </list>
 /// <para>
-///   An <see cref="InvalidOperationException" /> is thrown when the element also has an <c>hx-headers</c>
-///   attribute, or the <c>data-hx-headers</c> alias that HTMX reads as the same attribute, with or without
-///   HTMX 4.x modifiers, rather than losing one of the values. For HTMX 4.x,
-///   <see cref="HtmxV4Config.Prefix" /> determines the alias.
+///   An <see cref="InvalidOperationException" /> is thrown if the element already has an <c>hx-headers</c>
+///   attribute or its alias. The default alias is <c>data-hx-headers</c>;
+///   <see cref="HtmxV4Config.Prefix" /> determines the alias in HTMX 4.x.
+///   The check also covers attributes with HTMX 4.x modifiers, such as <c>hx-headers:inherited</c>.
 /// </para>
 /// </remarks>
 [HtmlTargetElement(Attributes = InheritedAttributeName)]
diff --git a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxRequestTagHelper.cs b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxRequestTagHelper.cs
index 5d24703..fe40778 100644
--- a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxRequestTagHelper.cs
+++ b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxRequestTagHelper.cs
@@ -24,10 +24,10 @@ namespace Ramstack.HtmxToolkit.TagHelpers;
 ///   If no supported option is set, the tag helper renders no attribute.
 /// </para>
 /// <para>
-///   An <see cref="InvalidOperationException" /> is thrown when the element also has the attribute
-///   that the tag helper renders for the selected version, or its <c>data-hx-*</c> alias that HTMX reads
-///   as the same attribute, with or without HTMX 4.x modifiers, rather than losing one of the values.
-///   For HTMX 4.x, <see cref="HtmxV4Config.Prefix" /> determines the alias.
+///   An <see cref="InvalidOperationException" /> is thrown if the element already has the attribute
+///   for the selected HTMX version or its alias. The default alias uses the <c>data-hx-</c>
+///   prefix; <see cref="HtmxV4Config.Prefix" /> determines the prefix in HTMX 4.x.
+///   The check also covers attributes with HTMX 4.x modifiers, such as <c>hx-config:inherited</c>.
 /// </para>
 /// </remarks>
 [HtmlTargetElement(Attributes = RequestInheritedAttributeName)]
diff --git a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxValsTagHelper.cs b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxValsTagHelper.cs
index 9299633..d396adf 100644
--- a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxValsTagHelper.cs
+++ b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxValsTagHelper.cs
@@ -25,10 +25,10 @@ namespace Ramstack.HtmxToolkit.TagHelpers;
 ///   <item>In HTMX 4.x, the <c>append</c> modifier merges a child declaration into inherited values.</item>
 /// </list>
 /// <para>
-///   An <see cref="InvalidOperationException" /> is thrown when the element also has an <c>hx-vals</c>
-///   attribute, or the <c>data-hx-vals</c> alias that HTMX reads as the same attribute, with or without
-///   HTMX 4.x modifiers, rather than losing one of the values. For HTMX 4.x,
-///   <see cref="HtmxV4Config.Prefix" /> determines the alias.
+///   An <see cref="InvalidOperationException" /> is thrown if the element already has an <c>hx-vals</c>
+///   attribute or its alias. The default alias is <c>data-hx-vals</c>;
+///   <see cref="HtmxV4Config.Prefix" /> determines the alias in HTMX 4.x.
+///   The check also covers attributes with HTMX 4.x modifiers, such as <c>hx-vals:inherited</c>.
 /// </para>
 /// </remarks>
 [HtmlTargetElement(Attributes = InheritedAttributeName)]