docs: correct and clarify XML comments and guides

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.

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
 

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)
     {

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.

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)]

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)]

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)]