From aef253dad523ad473133f373e07cf58367d70f99 Mon Sep 17 00:00:00 2001 From: rameel Date: Tue, 6 Oct 2026 23:57:43 +0500 Subject: [PATCH] docs: fix and clarify XML comments --- .../Configuration/HtmxFetchMode.cs | 6 +++--- .../Configuration/HtmxHistoryMode.cs | 2 +- .../Configuration/HtmxScrollBehavior.cs | 3 +-- .../Configuration/HtmxV1Config.cs | 8 ++++---- .../Configuration/HtmxV2Config.cs | 10 +++++++--- .../Configuration/HtmxV4Config.cs | 13 ++++++++----- .../Configuration/HttpVerb.cs | 18 +++++++++--------- .../Configuration/ResponseHandlingConfig.cs | 2 +- 8 files changed, 34 insertions(+), 28 deletions(-) diff --git a/src/Ramstack.HtmxToolkit/Configuration/HtmxFetchMode.cs b/src/Ramstack.HtmxToolkit/Configuration/HtmxFetchMode.cs index bdd2a0a..81f9d6e 100644 --- a/src/Ramstack.HtmxToolkit/Configuration/HtmxFetchMode.cs +++ b/src/Ramstack.HtmxToolkit/Configuration/HtmxFetchMode.cs @@ -6,9 +6,9 @@ namespace Ramstack.HtmxToolkit.Configuration; /// /// In HTMX 4.x this is passed as the mode option of the Fetch API. /// -/// In HTMX 1.x and 2.x, the equivalent setting is the selfRequestsOnly -/// boolean configuration option, for which corresponds to -/// and any other value corresponds to . +/// HTMX 1.x and 2.x use XMLHttpRequest instead of fetch. +/// Use or +/// to restrict requests to the current origin. /// /// public enum HtmxFetchMode diff --git a/src/Ramstack.HtmxToolkit/Configuration/HtmxHistoryMode.cs b/src/Ramstack.HtmxToolkit/Configuration/HtmxHistoryMode.cs index 1e42c7c..a1ff0a7 100644 --- a/src/Ramstack.HtmxToolkit/Configuration/HtmxHistoryMode.cs +++ b/src/Ramstack.HtmxToolkit/Configuration/HtmxHistoryMode.cs @@ -10,7 +10,7 @@ public enum HtmxHistoryMode /// /// /// 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 hx-history-cache extension. /// Enabled, diff --git a/src/Ramstack.HtmxToolkit/Configuration/HtmxScrollBehavior.cs b/src/Ramstack.HtmxToolkit/Configuration/HtmxScrollBehavior.cs index e332ddb..ccb2d33 100644 --- a/src/Ramstack.HtmxToolkit/Configuration/HtmxScrollBehavior.cs +++ b/src/Ramstack.HtmxToolkit/Configuration/HtmxScrollBehavior.cs @@ -1,7 +1,7 @@ namespace Ramstack.HtmxToolkit.Configuration; /// -/// Specifies the scrolling behavior for a boosted link during page transitions. +/// Specifies how HTMX scrolls elements into view with the show swap modifier. /// public enum HtmxScrollBehavior { @@ -17,7 +17,6 @@ public enum HtmxScrollBehavior /// /// Uses the instant scrolling behavior. - /// Supported only in HTMX 2.x. /// Instant } diff --git a/src/Ramstack.HtmxToolkit/Configuration/HtmxV1Config.cs b/src/Ramstack.HtmxToolkit/Configuration/HtmxV1Config.cs index b9bb20c..d9aa4d2 100644 --- a/src/Ramstack.HtmxToolkit/Configuration/HtmxV1Config.cs +++ b/src/Ramstack.HtmxToolkit/Configuration/HtmxV1Config.cs @@ -143,7 +143,7 @@ public bool? AllowEval } /// - /// Gets or sets a value indicating whether script tags should be processed in new content. + /// Gets or sets a value indicating whether <script> tags should be processed in new content. /// The HTMX default is . /// public bool? AllowScriptTags @@ -173,7 +173,7 @@ public string[]? AttributesToSettle } /// - /// Gets or sets a value indicating whether HTML template tags are used to parse content. + /// Gets or sets a value indicating whether HTML <template> tags are used to parse content. /// The HTMX default is . /// public bool? UseTemplateFragments @@ -244,7 +244,7 @@ public bool? SelfRequestsOnly } /// - /// Gets or sets the scrolling behavior for boosted links. + /// Gets or sets the scrolling behavior used by the show modifier of hx-swap. /// The HTMX default is . /// [JsonConverter(typeof(HtmxScrollBehaviorJsonConverter))] @@ -265,7 +265,7 @@ public bool? DefaultFocusScroll } /// - /// Gets or sets a value indicating whether GET requests use a cache-busting parameter. + /// Gets or sets a value indicating whether GET requests use a cache-busting parameter. /// The HTMX default is . /// public bool? GetCacheBusterParam diff --git a/src/Ramstack.HtmxToolkit/Configuration/HtmxV2Config.cs b/src/Ramstack.HtmxToolkit/Configuration/HtmxV2Config.cs index c6df3b6..ddcceae 100644 --- a/src/Ramstack.HtmxToolkit/Configuration/HtmxV2Config.cs +++ b/src/Ramstack.HtmxToolkit/Configuration/HtmxV2Config.cs @@ -143,7 +143,7 @@ public bool? AllowEval } /// - /// Gets or sets a value indicating whether script tags should be processed in new content. + /// Gets or sets a value indicating whether <script> tags should be processed in new content. /// The HTMX default is . /// public bool? AllowScriptTags @@ -186,6 +186,7 @@ public string[]? AttributesToSettle /// Gets or sets the WebSocket reconnection delay strategy. /// The HTMX default is full-jitter. /// + /// Requires the HTMX WebSocket extension. 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 . /// + /// Requires the HTMX WebSocket extension. [JsonConverter(typeof(HtmxBinaryTypeJsonConverter))] public HtmxBinaryType? WsBinaryType { @@ -254,7 +256,7 @@ public bool? SelfRequestsOnly } /// - /// Gets or sets the scrolling behavior for boosted links. + /// Gets or sets the scrolling behavior used by the show modifier of hx-swap. /// The HTMX default is . /// [JsonConverter(typeof(HtmxScrollBehaviorJsonConverter))] @@ -275,7 +277,7 @@ public bool? DefaultFocusScroll } /// - /// Gets or sets a value indicating whether GET requests use a cache-busting parameter. + /// Gets or sets a value indicating whether GET requests use a cache-busting parameter. /// The HTMX default is . /// public bool? GetCacheBusterParam @@ -362,6 +364,7 @@ public bool? AllowNestedOobSwaps /// as HTMX requests. /// The HTMX default is . /// + /// Available since HTMX 2.0.5. public bool? HistoryRestoreAsHxRequest { get; @@ -373,6 +376,7 @@ public bool? HistoryRestoreAsHxRequest /// a request is issued. /// The HTMX default is . /// + /// Available since HTMX 2.0.7. public bool? ReportValidityOfForms { get; diff --git a/src/Ramstack.HtmxToolkit/Configuration/HtmxV4Config.cs b/src/Ramstack.HtmxToolkit/Configuration/HtmxV4Config.cs index 1d3f80d..ca3bb1f 100644 --- a/src/Ramstack.HtmxToolkit/Configuration/HtmxV4Config.cs +++ b/src/Ramstack.HtmxToolkit/Configuration/HtmxV4Config.cs @@ -54,11 +54,14 @@ public HtmxSwap? DefaultSwap /// /// Gets or sets a value indicating whether the main swap is performed - /// when the response contained only out-of-band elements. - /// <hx-partial> content always prevents the main swap. - /// The HTMX default is and can be overridden - /// using the swapEmpty modifier on hx-swap. + /// when no content remains after processing out-of-band elements. + /// The HTMX default is . /// + /// + /// Processed <hx-partial> elements suppress an empty main swap regardless + /// of this setting. The swapEmpty modifier on hx-swap overrides either default. + /// Nonempty main content is still swapped, and the swap style always runs. + /// [JsonPropertyName("allowEmptySwapAfterOOB")] public bool? AllowEmptySwapAfterOob { @@ -149,7 +152,7 @@ public int? DefaultTimeout /// /// Gets or sets the request mode passed to the Fetch API. - /// The HTMX default is same-origin. + /// The HTMX default is . /// [JsonConverter(typeof(HtmxFetchModeJsonConverter))] public HtmxFetchMode? Mode diff --git a/src/Ramstack.HtmxToolkit/Configuration/HttpVerb.cs b/src/Ramstack.HtmxToolkit/Configuration/HttpVerb.cs index bf0ea86..5bd114f 100644 --- a/src/Ramstack.HtmxToolkit/Configuration/HttpVerb.cs +++ b/src/Ramstack.HtmxToolkit/Configuration/HttpVerb.cs @@ -6,52 +6,52 @@ namespace Ramstack.HtmxToolkit.Configuration; public enum HttpVerb { /// - /// The GET method requests a representation of the specified resource. + /// The GET method requests a representation of the specified resource. /// Get, /// - /// The HEAD method requests a response identical to a GET response, + /// The HEAD method requests a response identical to a GET response, /// but without the response body. /// Head, /// - /// The POST method submits an entity to the specified resource. + /// The POST method submits an entity to the specified resource. /// Post, /// - /// The PUT method replaces all current representations of the target resource + /// The PUT method replaces all current representations of the target resource /// with the request payload. /// Put, /// - /// The DELETE method deletes the specified resource. + /// The DELETE method deletes the specified resource. /// Delete, /// - /// The CONNECT method establishes a tunnel to the server + /// The CONNECT method establishes a tunnel to the server /// identified by the target resource. /// Connect, /// - /// The OPTIONS method describes the communication options + /// The OPTIONS method describes the communication options /// for the target resource. /// Options, /// - /// The TRACE method performs a message loop-back test + /// The TRACE method performs a message loop-back test /// along the path to the target resource. /// Trace, /// - /// The PATCH method applies partial modifications to a resource. + /// The PATCH method applies partial modifications to a resource. /// Patch } diff --git a/src/Ramstack.HtmxToolkit/Configuration/ResponseHandlingConfig.cs b/src/Ramstack.HtmxToolkit/Configuration/ResponseHandlingConfig.cs index ffb187e..6383234 100644 --- a/src/Ramstack.HtmxToolkit/Configuration/ResponseHandlingConfig.cs +++ b/src/Ramstack.HtmxToolkit/Configuration/ResponseHandlingConfig.cs @@ -22,7 +22,7 @@ public sealed class ResponseHandlingConfig public bool? Error { get; set; } /// - /// 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 <title> tags in the response. /// public bool? IgnoreTitle { get; set; }