From 088eca708bbed8dd794180188d1e77e025c13c00 Mon Sep 17 00:00:00 2001 From: rameel Date: Mon, 5 Oct 2026 23:56:26 +0500 Subject: [PATCH] docs: fix and clarify XML documentation --- .../Hosting/ServiceCollectionExtensions.cs | 2 +- src/Ramstack.HtmxToolkit/HtmxFieldValues.cs | 33 ++++++-------- .../HtmxLocationOptions.cs | 30 +++++++++---- .../HtmxRequestHeaderNames.cs | 29 +++++++++---- .../HtmxRequestHeaders.cs | 43 ++++++++++++------- src/Ramstack.HtmxToolkit/HtmxResponse.cs | 7 +-- .../HtmxResponseHeaderNames.cs | 2 +- .../HtmxResponseHeaders.cs | 4 +- src/Ramstack.HtmxToolkit/HtmxSwap.cs | 6 +-- .../HttpResponseExtensions.cs | 4 +- .../Internal/EnumHelper.cs | 6 +-- .../TagHelpers/HtmxConfigTagHelper.cs | 2 +- .../TagHelpers/HtmxRequestTagHelper.cs | 16 +++++-- .../TagHelpers/HtmxUrlTagHelper.cs | 3 +- 14 files changed, 112 insertions(+), 75 deletions(-) diff --git a/src/Ramstack.HtmxToolkit/Hosting/ServiceCollectionExtensions.cs b/src/Ramstack.HtmxToolkit/Hosting/ServiceCollectionExtensions.cs index 607e972..285367d 100644 --- a/src/Ramstack.HtmxToolkit/Hosting/ServiceCollectionExtensions.cs +++ b/src/Ramstack.HtmxToolkit/Hosting/ServiceCollectionExtensions.cs @@ -15,7 +15,7 @@ public static class ServiceCollectionExtensions /// The service collection. /// An optional delegate used to configure HTMX Toolkit. /// - /// The same service collection. + /// The same collection. /// public static IServiceCollection AddHtmxToolkit(this IServiceCollection services, Action? configure = null) { diff --git a/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs index 206f026..0a7a13f 100644 --- a/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs +++ b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs @@ -54,22 +54,20 @@ public string this[int index] } /// - /// Gets the underlying storage: a string, a string array, or . + /// Gets the underlying storage: a , an array of values, + /// or . /// internal object? Values => _values; /// - /// Initializes a new instance of the structure - /// with a single value. + /// Initializes a new instance of the structure with a single value. /// - /// The value to store, or - /// to represent no values. + /// The value to store, or to represent no values. public HtmxFieldValues(string? value) => _values = value; /// - /// Initializes a new instance of the structure - /// with the specified values. + /// Initializes a new instance of the structure with the specified values. /// /// The specified array is stored directly and is not copied. /// The values to store, or @@ -95,7 +93,7 @@ public static HtmxFieldValues Create(ReadOnlySpan values) } /// - /// Converts a string to an . + /// Converts a to an . /// /// The value to convert, or /// to represent no values. @@ -106,10 +104,9 @@ public static implicit operator HtmxFieldValues(string? value) => new(value); /// - /// Converts an array of strings to an . + /// Converts an array of values to an . /// - /// The values to convert, or - /// to represent no values. + /// The values to convert, or to represent no values. /// /// An containing . /// @@ -152,14 +149,8 @@ private static string OutOfBounds() => /// Copies the specified read-only span to a new array. /// /// - /// - /// The JIT compiler inlines the implementation of - /// into its caller, producing a disproportionately large amount of native code - /// at the call site. - /// - /// - /// This non-inlined wrapper keeps that implementation out of . - /// + /// This non-inlined wrapper keeps the implementation of + /// out of to limit native code growth at its call sites. /// /// The values to copy. /// @@ -172,7 +163,7 @@ private static string[] CreateArray(ReadOnlySpan s) => #region Inner type: Enumerator /// - /// Enumerates the strings represented by an . + /// Enumerates the string values represented by an . /// public struct Enumerator : IEnumerator { @@ -186,7 +177,7 @@ public struct Enumerator : IEnumerator /// /// Initializes a new enumerator for the specified . /// - /// The value whose strings to enumerate. + /// The value containing the strings to enumerate. public Enumerator(HtmxFieldValues value) { if (value.Values is string s) diff --git a/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs index e585871..4793d0c 100644 --- a/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs +++ b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs @@ -16,13 +16,13 @@ public sealed class HtmxLocationOptions public string? Path { get; internal set; } /// - /// Gets or sets the source element that initiated the request. + /// Gets or sets the CSS selector for the element used as the source of the new request. /// /// Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x. public string? Source { get; set; } /// - /// Gets or sets the target element into which the response will be swapped. + /// Gets or sets the selector for the target element into which the response will be swapped. /// /// Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x. public string? Target { get; set; } @@ -37,14 +37,27 @@ public sealed class HtmxLocationOptions /// /// Gets or sets the form field values to submit with the request. /// - /// Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x. + /// + /// Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x. + /// + /// HTMX 1.9.x and 2.x submit array values as repeated parameters. + /// HTMX 4.0.0 converts an array to a single comma-separated field value. + /// + /// public IDictionary? Values { get; set; } /// /// Gets or sets the headers to include with the request. - /// Header values must be strings. Pass complex data as a pre-serialized JSON string. /// - /// Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x. + /// + /// + /// Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x. + /// + /// + /// Header values must be strings. + /// Pass complex data as a pre-serialized JSON string. + /// + /// public IDictionary? Headers { get; set; } /// @@ -54,9 +67,10 @@ public sealed class HtmxLocationOptions public string? Select { get; set; } /// - /// Gets or sets a selector used to select content for out-of-band swaps from the response. + /// Gets or sets a comma-separated list of selectors, optionally followed by swap styles, + /// used to select content for out-of-band swaps from the response. /// - /// Supported in HTMX 2.x and HTMX 4.x. + /// Supported in HTMX 2.0.8 and later 2.x releases, and in HTMX 4.x. [JsonPropertyName("selectOOB")] public string? SelectOob { get; set; } @@ -64,7 +78,7 @@ public sealed class HtmxLocationOptions /// Gets or sets the path to push into the browser history. /// Set this property to "false" to prevent the URL from being pushed. /// - /// Supported in HTMX 2.x and HTMX 4.x. + /// Supported in HTMX 2.0.8 and later 2.x releases, and in HTMX 4.x. public string? Push { get; set; } /// diff --git a/src/Ramstack.HtmxToolkit/HtmxRequestHeaderNames.cs b/src/Ramstack.HtmxToolkit/HtmxRequestHeaderNames.cs index c92dccd..3483de5 100644 --- a/src/Ramstack.HtmxToolkit/HtmxRequestHeaderNames.cs +++ b/src/Ramstack.HtmxToolkit/HtmxRequestHeaderNames.cs @@ -9,8 +9,8 @@ namespace Ramstack.HtmxToolkit; public static class HtmxRequestHeaderNames { /// - /// The HX-Boosted header indicates whether the request was made using AJAX - /// instead of a normal navigation. + /// The HX-Boosted header indicates that the request came from a link or form + /// enhanced with hx-boost. /// public const string Boosted = "HX-Boosted"; @@ -21,16 +21,21 @@ public static class HtmxRequestHeaderNames /// /// The HX-History-Restore-Request header indicates whether the request - /// is for history restoration after a miss in the local history cache. + /// fetches content for history restoration. /// + /// + /// HTMX 1.x and 2.x send this header after a history cache miss. + /// HTMX 4.x refetches history content by default; local caching requires an extension. + /// public const string HistoryRestoreRequest = "HX-History-Restore-Request"; /// /// The HX-Prompt header contains the user's response to an hx-prompt. /// /// - /// Supported only in HTMX 1.x and 2.x. HTMX 4.x removed hx-prompt - /// and does not send this header. + /// Supported natively in HTMX 1.x and 2.x. In HTMX 4.x, the + /// hx-prompt extension + /// restores this header. /// public const string Prompt = "HX-Prompt"; @@ -54,7 +59,9 @@ public static class HtmxRequestHeaderNames /// The HX-Source header identifies the element that triggered the request. /// /// - /// Supported only in HTMX 4.x. The value is in tag#id format, for example button#submit. + /// Supported only in HTMX 4.x. The value contains the lowercase tag name and, + /// when the element has an ID, # followed by its URI-encoded ID. + /// Examples include button#submit and button. /// public const string Source = "HX-Source"; @@ -63,12 +70,16 @@ public static class HtmxRequestHeaderNames /// /// /// In HTMX 1.x and 2.x, the value is the ID of the target element. - /// In HTMX 4.x, the value is in tag#id format, for example div#results. + /// + /// In HTMX 4.x, the value contains the lowercase tag name and, when the element has an ID, + /// # followed by its URI-encoded ID. Examples include div#results and body. + /// /// public const string Target = "HX-Target"; /// - /// The HX-Trigger-Name header contains the name of the triggered element, if present. + /// The HX-Trigger-Name header contains the name attribute of the element + /// that issued the request, if present. /// /// /// Supported only in HTMX 1.x and 2.x. HTMX 4.x identifies the source element with HX-Source instead. @@ -76,7 +87,7 @@ public static class HtmxRequestHeaderNames public const string TriggerName = "HX-Trigger-Name"; /// - /// The HX-Trigger header contains the ID of the triggered element, if present. + /// The HX-Trigger header contains the ID of the element that issued the request, if present. /// /// /// Supported only in HTMX 1.x and 2.x. HTMX 4.x identifies the source element with HX-Source instead. diff --git a/src/Ramstack.HtmxToolkit/HtmxRequestHeaders.cs b/src/Ramstack.HtmxToolkit/HtmxRequestHeaders.cs index 07783dd..6e32f9d 100644 --- a/src/Ramstack.HtmxToolkit/HtmxRequestHeaders.cs +++ b/src/Ramstack.HtmxToolkit/HtmxRequestHeaders.cs @@ -22,8 +22,8 @@ internal HtmxRequestHeaders(HttpRequest request) => _headers = request.Headers; /// - /// Gets a value indicating whether the request was made - /// using AJAX instead of a normal navigation. + /// Gets a value indicating whether the request came from a link + /// or form enhanced with hx-boost. /// /// /// The header name is . @@ -39,11 +39,14 @@ internal HtmxRequestHeaders(HttpRequest request) => public string? CurrentUrl => GetString(_headers, HtmxRequestHeaderNames.CurrentUrl); /// - /// Gets a value indicating whether the request restores history - /// after a miss in the local history cache. + /// Gets a value indicating whether the request fetches content for history restoration. /// /// - /// The header name is . + /// The header name is . + /// + /// HTMX 1.x and 2.x send this header after a history cache miss. + /// HTMX 4.x refetches history content by default; local caching requires an extension. + /// /// public bool HistoryRestoreRequest => GetBoolean(_headers, HtmxRequestHeaderNames.HistoryRestoreRequest); @@ -53,8 +56,9 @@ internal HtmxRequestHeaders(HttpRequest request) => /// /// The header name is . /// - /// Supported only in HTMX 1.x and 2.x; HTMX 4.x removed hx-prompt - /// and does not send this header. + /// Supported natively in HTMX 1.x and 2.x. In HTMX 4.x, the + /// hx-prompt extension + /// restores this header. /// /// public string? Prompt => GetString(_headers, HtmxRequestHeaderNames.Prompt); @@ -79,7 +83,6 @@ internal HtmxRequestHeaders(HttpRequest request) => /// and "full" for body-level or hx-select requests. /// /// - /// Returns when the header is absent. /// The request type is not inferred from boosted navigation. /// /// @@ -111,7 +114,9 @@ static HtmxRequestType GetRequestType(IHeaderDictionary dictionary) /// /// The header name is . /// - /// Supported only in HTMX 4.x. The value is in tag#id format, for example button#submit. + /// Supported only in HTMX 4.x. The value contains the lowercase tag name and, + /// when the element has an ID, # followed by its URI-encoded ID. + /// Examples include button#submit and button. /// /// public string? Source => GetString(_headers, HtmxRequestHeaderNames.Source); @@ -122,12 +127,16 @@ static HtmxRequestType GetRequestType(IHeaderDictionary dictionary) /// /// The header name is . /// In HTMX 1.x and 2.x, the value is the ID of the target element. - /// In HTMX 4.x, the value is in tag#id format, for example div#results. + /// + /// In HTMX 4.x, the value contains the lowercase tag name and, + /// when the element has an ID, # followed by its URI-encoded ID. + /// Examples include div#results and body. + /// /// public string? Target => GetString(_headers, HtmxRequestHeaderNames.Target); /// - /// Gets the name of the triggered element, if present. + /// Gets the name attribute of the element that issued the request, if present. /// /// /// The header name is . @@ -139,12 +148,13 @@ static HtmxRequestType GetRequestType(IHeaderDictionary dictionary) public string? TriggerName => GetString(_headers, HtmxRequestHeaderNames.TriggerName); /// - /// Gets the ID of the triggered element, if present. + /// Gets the ID of the element that issued the request, if present. /// /// /// The header name is . /// - /// Supported only in HTMX 1.x and 2.x; HTMX 4.x identifies the source element with HX-Source instead. + /// Supported only in HTMX 1.x and 2.x; HTMX 4.x identifies the source element + /// with HX-Source instead. /// /// public string? Trigger => GetString(_headers, HtmxRequestHeaderNames.Trigger); @@ -155,7 +165,8 @@ static HtmxRequestType GetRequestType(IHeaderDictionary dictionary) /// The header collection to inspect. /// The name of the header. /// - /// if the header value is "true"; otherwise, . + /// if the header value is "true"; + /// otherwise, . /// private static bool GetBoolean(IHeaderDictionary dictionary, string key) => dictionary.TryGetValue(key, out var value) && value is ["true"]; @@ -184,8 +195,8 @@ private static bool GetBoolean(IHeaderDictionary dictionary, string key) => private sealed class HtmxRequestHeadersDebugView(HtmxRequestHeaders headers) { /// - /// Gets the collection of all HTTP headers stored - /// in the associated instance + /// Gets the collection of request headers whose names start with HX- + /// from the associated instance /// as an array of key-value pairs. /// [DebuggerBrowsable(DebuggerBrowsableState.RootHidden)] diff --git a/src/Ramstack.HtmxToolkit/HtmxResponse.cs b/src/Ramstack.HtmxToolkit/HtmxResponse.cs index 0db6007..d8dbf24 100644 --- a/src/Ramstack.HtmxToolkit/HtmxResponse.cs +++ b/src/Ramstack.HtmxToolkit/HtmxResponse.cs @@ -103,7 +103,7 @@ public HtmxResponse PreventPushUrl() => SetHeader(this, HtmxResponseHeaderNames.PushUrl, "false"); /// - /// Sets the HX-Redirect header to perform a client-side redirect to a new location. + /// Sets the HX-Redirect header to perform a client-side redirect with a full-page reload. /// /// The header value to set. /// @@ -243,7 +243,8 @@ static HtmxResponse TriggerEventImpl(HtmxResponse response, string eventName, ob /// The event detail type. /// The event name to trigger. /// The event detail. - /// The source-generated JSON metadata for the event detail. + /// The JSON metadata for the event detail. + /// Use source-generated metadata for trimming and Native AOT. /// The event timing. Defaults to . /// /// The current instance. @@ -306,7 +307,7 @@ private static HtmxResponse AddToPendingEvent(HtmxResponse response, string even private sealed class HtmxResponseDebugView(HtmxResponse response) { /// - /// Gets the collection of HTTP response headers + /// Gets the collection of HTMX response headers /// from the associated instance /// as an array of key-value pairs. /// diff --git a/src/Ramstack.HtmxToolkit/HtmxResponseHeaderNames.cs b/src/Ramstack.HtmxToolkit/HtmxResponseHeaderNames.cs index f9bbf6f..166ffb6 100644 --- a/src/Ramstack.HtmxToolkit/HtmxResponseHeaderNames.cs +++ b/src/Ramstack.HtmxToolkit/HtmxResponseHeaderNames.cs @@ -19,7 +19,7 @@ public static class HtmxResponseHeaderNames public const string PushUrl = "HX-Push-Url"; /// - /// The HX-Redirect header performs a client-side redirect to a new location. + /// The HX-Redirect header performs a client-side redirect with a full-page reload. /// public const string Redirect = "HX-Redirect"; diff --git a/src/Ramstack.HtmxToolkit/HtmxResponseHeaders.cs b/src/Ramstack.HtmxToolkit/HtmxResponseHeaders.cs index 5fd5f41..a46093e 100644 --- a/src/Ramstack.HtmxToolkit/HtmxResponseHeaders.cs +++ b/src/Ramstack.HtmxToolkit/HtmxResponseHeaders.cs @@ -45,7 +45,7 @@ public string PushUrl /// /// Gets or sets the value of the HX-Redirect header, which performs - /// a client-side redirect to a new location. + /// a client-side redirect with a full-page reload. /// [MaybeNull] public string Redirect @@ -218,7 +218,7 @@ private static void SetHeader(IHeaderDictionary headers, string key, string? val private sealed class HtmxResponseHeadersDebugView(HtmxResponseHeaders headers) { /// - /// Gets the collection of HTTP response headers + /// Gets the collection of HTMX response headers /// from the associated instance /// as an array of key-value pairs. /// diff --git a/src/Ramstack.HtmxToolkit/HtmxSwap.cs b/src/Ramstack.HtmxToolkit/HtmxSwap.cs index 9d79d6a..5835519 100644 --- a/src/Ramstack.HtmxToolkit/HtmxSwap.cs +++ b/src/Ramstack.HtmxToolkit/HtmxSwap.cs @@ -25,7 +25,7 @@ public enum HtmxSwap /// /// With HTMX 1.9.x or 2.x, activate the ramstack-morph extension /// and optionally load Idiomorph. Without Idiomorph, the extension - /// falls back to innerHTML. + /// falls back to . /// /// InnerMorph, @@ -40,7 +40,7 @@ public enum HtmxSwap /// /// With HTMX 1.9.x or 2.x, activate the ramstack-morph extension /// and optionally load Idiomorph. Without Idiomorph, the extension - /// falls back to outerHTML. + /// falls back to . /// /// OuterMorph, @@ -54,7 +54,7 @@ public enum HtmxSwap /// /// /// With HTMX 1.9.x or 2.x, activate the ramstack-morph extension - /// to fall back to attribute synchronization and innerHTML. + /// to fall back to attribute synchronization and . /// /// OuterSync, diff --git a/src/Ramstack.HtmxToolkit/HttpResponseExtensions.cs b/src/Ramstack.HtmxToolkit/HttpResponseExtensions.cs index bfd75bc..a4cde7d 100644 --- a/src/Ramstack.HtmxToolkit/HttpResponseExtensions.cs +++ b/src/Ramstack.HtmxToolkit/HttpResponseExtensions.cs @@ -18,7 +18,7 @@ public static HtmxResponseHeaders GetHtmxHeaders(this HttpResponse response) => new(response); /// - /// Configures the HTMX response headers. + /// Configures the HTMX response headers when the current request is an HTMX request. /// /// The HTTP response to configure. /// The delegate that configures the HTMX response headers. @@ -29,7 +29,7 @@ public static void Htmx(this HttpResponse response, Action configu } /// - /// Configures the HTMX response headers. + /// Configures the HTMX response headers when the current request is an HTMX request. /// /// The HTTP response to configure. /// The delegate that configures the HTMX response headers diff --git a/src/Ramstack.HtmxToolkit/Internal/EnumHelper.cs b/src/Ramstack.HtmxToolkit/Internal/EnumHelper.cs index 9f60888..6ffbb0d 100644 --- a/src/Ramstack.HtmxToolkit/Internal/EnumHelper.cs +++ b/src/Ramstack.HtmxToolkit/Internal/EnumHelper.cs @@ -49,12 +49,12 @@ or HtmxScrollBehavior.Smooth /// /// Converts a value to its corresponding string representation, - /// or returns if the value is . + /// or returns if is . /// /// The nullable value. /// - /// The string representation of the value, - /// or if the value is . + /// The string representation of , + /// or if is . /// public static string? GetSwapValue(this HtmxSwap? value) => value?.GetSwapValue(); diff --git a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxConfigTagHelper.cs b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxConfigTagHelper.cs index 4f31f6d..e43e63a 100644 --- a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxConfigTagHelper.cs +++ b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxConfigTagHelper.cs @@ -9,7 +9,7 @@ namespace Ramstack.HtmxToolkit.TagHelpers; /// -/// Renders the application-wide HTMX configuration as a meta element. +/// Renders the application-wide HTMX configuration as a <meta> element. /// /// The service used to generate antiforgery tokens. /// The configured HTMX Toolkit options. diff --git a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxRequestTagHelper.cs b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxRequestTagHelper.cs index d5aedb5..e4f2692 100644 --- a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxRequestTagHelper.cs +++ b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxRequestTagHelper.cs @@ -102,9 +102,13 @@ public HtmxRequestCredentials? Credentials } /// - /// Gets or sets a value indicating whether HTMX-specific request headers are omitted. + /// Gets or sets a value indicating whether headers set by HTMX are omitted, + /// including custom headers supplied through hx-headers. /// - /// Supported in HTMX 1.x and 2.x. Removed in HTMX 4.x. + /// + /// Supported in HTMX 1.x and 2.x. Removed in HTMX 4.x. + /// Headers added by the browser are unaffected. + /// [HtmlAttributeName(RequestNoHeadersAttributeName)] public bool? NoHeaders { @@ -135,9 +139,13 @@ public string? Redirect } /// - /// Gets or sets the referrer URL or referrer policy for the request. + /// Gets or sets the Fetch API referrer value for the request. /// - /// Supported only in HTMX 4.x. + /// + /// Supported only in HTMX 4.x. Accepts a same-origin URL, an empty string to omit + /// the referrer, or about:client to use the default referrer. + /// The separate Fetch API referrerPolicy option is not configured by this property. + /// [HtmlAttributeName(RequestReferrerAttributeName)] public string? Referrer { diff --git a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs index 71abdb7..f48a7cb 100644 --- a/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs +++ b/src/Ramstack.HtmxToolkit/TagHelpers/HtmxUrlTagHelper.cs @@ -65,7 +65,8 @@ public sealed class HtmxUrlTagHelper(IUrlHelperFactory factory) : TagHelper /// Gets or sets the name of the area. /// /// - /// Must be if is not . + /// Can be combined with a named route, controller action, or Razor Page. + /// When not , overrides any area value in . /// [AspMvcArea] [HtmlAttributeName(AreaAttributeName)]