Add comprehensive XML documentation to faceted builders

Completes Phase 3 of documentation improvement by adding detailed
XML documentation to all faceted builder classes. These builders
configure specific aspects of PDF conversion requests.

Documented classes:
- ConfigBuilder: Request-level settings (page ranges, webhooks, trace ID)
- HtmlConversionBehaviorBuilder: Chromium rendering behaviors (improved AddAdditionalHeaders docs)
- WebhookBuilder: Async PDF generation callbacks
- UrlHeaderFooterBuilder: Custom headers/footers for URL conversions
- UrlExtraResourcesBuilder: CSS/JS injection for URL conversions

Key improvements:
- Explained webhook purpose and Docker networking considerations
- Clarified trace ID usage for distributed system correlation
- Documented extra resources (CSS/JS injection) purpose and usage
- Added HTTP header injection use cases (authentication, correlation)
- Explained error URL callback functionality

All builder documentation follows consistent format with clear
parameter descriptions, return types, and exception documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Jaben

src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/ConfigBuilder.cs

@@ -17,6 +17,9 @@
 
 namespace Gotenberg.Sharp.API.Client.Domain.Builders.Faceted;
 
+/// <summary>
+/// Configures request-level settings including page ranges, webhooks, result filename, and trace ID for correlation.
+/// </summary>
 public sealed class ConfigBuilder
 {
     private readonly RequestConfig _requestConfig;
@@ -26,13 +29,23 @@ internal ConfigBuilder(RequestConfig requestConfig)
         this._requestConfig = requestConfig;
     }
 
+    /// <summary>
+    /// Specifies which pages to include in the resulting PDF using Chrome print format (e.g., "1-3,5,7-9").
+    /// </summary>
+    /// <param name="pageRanges">Page range specification string, or null for all pages.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public ConfigBuilder SetPageRanges(string? pageRanges)
     {
         this._requestConfig.PageRanges = Pages.PageRanges.Create(pageRanges);
 
         return this;
     }
 
+    /// <summary>
+    /// Sets page ranges using a PageRanges instance.
+    /// </summary>
+    /// <param name="pageRanges">Pre-configured PageRanges instance, or null for all pages.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public ConfigBuilder SetPageRanges(PageRanges? pageRanges)
     {
         this._requestConfig.PageRanges = pageRanges ?? Pages.PageRanges.All;
@@ -46,6 +59,13 @@ public ConfigBuilder PageRanges(string pageRanges)
         return this.SetPageRanges(pageRanges);
     }
 
+    /// <summary>
+    /// Sets the suggested filename for the resulting PDF when Gotenberg returns it.
+    /// Useful when using webhooks to identify which request generated which PDF.
+    /// </summary>
+    /// <param name="resultFileName">Desired filename for the PDF result.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    /// <exception cref="ArgumentException">Thrown when filename is null or empty.</exception>
     public ConfigBuilder SetResultFileName(string resultFileName)
     {
         if (resultFileName.IsNotSet())
@@ -62,6 +82,13 @@ public ConfigBuilder ResultFileName(string resultFileName)
         return this.SetResultFileName(resultFileName);
     }
 
+    /// <summary>
+    /// Sets a trace ID for correlating this request across logs and metrics in both your application and Gotenberg.
+    /// Useful for debugging and monitoring distributed systems.
+    /// </summary>
+    /// <param name="trace">Trace or correlation ID for this request.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    /// <exception cref="ArgumentException">Thrown when trace is null or empty.</exception>
     public ConfigBuilder SetTrace(string trace)
     {
         if (trace.IsNotSet())
@@ -72,6 +99,12 @@ public ConfigBuilder SetTrace(string trace)
         return this;
     }
 
+    /// <summary>
+    /// Configures webhook settings for asynchronous PDF generation. When configured, Gotenberg will POST the
+    /// generated PDF to the specified URL instead of returning it in the response.
+    /// </summary>
+    /// <param name="action">Configuration action for webhook settings.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public ConfigBuilder AddWebhook(Action<WebhookBuilder> action)
     {
         if (action == null) throw new ArgumentNullException(nameof(action));
@@ -83,6 +116,11 @@ public ConfigBuilder AddWebhook(Action<WebhookBuilder> action)
         return this;
     }
 
+    /// <summary>
+    /// Sets pre-configured webhook settings.
+    /// </summary>
+    /// <param name="webhook">Pre-configured Webhook instance.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public ConfigBuilder SetWebhook(Webhook webhook)
     {
         this._requestConfig.Webhook = webhook ?? throw new ArgumentNullException(nameof(webhook));

src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/HtmlConversionBehaviorBuilder.cs

@@ -17,6 +17,10 @@
 
 namespace Gotenberg.Sharp.API.Client.Domain.Builders.Faceted;
 
+/// <summary>
+/// Configures Chromium rendering behaviors for HTML and URL to PDF conversions.
+/// Includes settings for wait delays, HTTP headers, cookies, metadata, PDF format, and accessibility.
+/// </summary>
 public sealed class HtmlConversionBehaviorBuilder
 {
     private readonly HtmlConversionBehaviors _htmlConversionBehaviors;
@@ -79,13 +83,13 @@ public HtmlConversionBehaviorBuilder SetUserAgent(string userAgent)
     }
 
     /// <summary>
-    ///     Sets extra HTTP headers that Chromium will send when loading the HTML
+    /// Adds custom HTTP headers that Chromium will send when loading the HTML. Useful for authentication tokens,
+    /// custom request identification, or triggering specific server behavior.
     /// </summary>
-    /// <param name="headerName"></param>
-    /// <param name="headerValue"></param>
-    /// <returns></returns>
-    /// <exception cref="InvalidOperationException"></exception>
-    /// <exception cref="JsonReaderException"></exception>
+    /// <param name="headerName">HTTP header name.</param>
+    /// <param name="headerValue">HTTP header value.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when header name or value is invalid.</exception>
     public HtmlConversionBehaviorBuilder AddAdditionalHeaders(string headerName, string headerValue)
     {
         var header = string.Format("{0}{2}{1}", "{", "}", $"{'"'}{headerName}{'"'} : {'"'}{headerValue}{'"'}");
@@ -94,11 +98,11 @@ public HtmlConversionBehaviorBuilder AddAdditionalHeaders(string headerName, str
     }
 
     /// <summary>
-    ///     Sets extra HTTP headers that Chromium will send when loading the HTML
+    /// Adds multiple custom HTTP headers as a JSON object. Useful for adding several headers at once.
     /// </summary>
-    /// <param name="extraHeaders"></param>
-    /// <returns></returns>
-    /// <exception cref="InvalidOperationException"></exception>
+    /// <param name="extraHeaders">JSON object containing header name-value pairs.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when extraHeaders is null.</exception>
     public HtmlConversionBehaviorBuilder AddAdditionalHeaders(JObject extraHeaders)
     {
         if (extraHeaders == null)

src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/UrlExtraResourcesBuilder.cs

@@ -19,21 +19,38 @@
 
 namespace Gotenberg.Sharp.API.Client.Domain.Builders.Faceted;
 
+/// <summary>
+/// Injects additional CSS stylesheets or JavaScript files into a URL-based PDF conversion before rendering.
+/// Useful for adding custom styling or scripts to pages you don't control.
+/// </summary>
+/// <remarks>
+/// Link tags inject CSS stylesheets (&lt;link rel="stylesheet"&gt;).
+/// Script tags inject JavaScript files (&lt;script src="..."&gt;).
+/// </remarks>
 public sealed class UrlExtraResourcesBuilder(ExtraUrlResources extraUrlResources)
 {
     #region add one
 
     #region link tag
 
-    
+    /// <summary>
+    /// Injects a CSS stylesheet link tag into the page before rendering.
+    /// </summary>
+    /// <param name="url">URL of the CSS stylesheet to inject.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when URL is null or empty.</exception>
     public UrlExtraResourcesBuilder AddLinkTag(string url)
     {
         if (url.IsNotSet()) throw new InvalidOperationException(nameof(url));
 
         return this.AddLinkTag(new Uri(url));
     }
 
-    
+    /// <summary>
+    /// Injects a CSS stylesheet link tag into the page before rendering.
+    /// </summary>
+    /// <param name="url">URI of the CSS stylesheet to inject.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlExtraResourcesBuilder AddLinkTag(Uri url)
     {
         return this.AddItem(new ExtraUrlResourceItem(url, ExtraUrlResourceType.LinkTag));
@@ -43,15 +60,24 @@ public UrlExtraResourcesBuilder AddLinkTag(Uri url)
 
     #region script tag
 
-    
+    /// <summary>
+    /// Injects a JavaScript script tag into the page before rendering.
+    /// </summary>
+    /// <param name="url">URL of the JavaScript file to inject.</param>
+    /// <returns>The builder instance for method chaining.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when URL is null or empty.</exception>
     public UrlExtraResourcesBuilder AddScriptTag(string url)
     {
         if (url.IsNotSet()) throw new InvalidOperationException(nameof(url));
 
         return this.AddScriptTag(new Uri(url));
     }
 
-    
+    /// <summary>
+    /// Injects a JavaScript script tag into the page before rendering.
+    /// </summary>
+    /// <param name="url">URI of the JavaScript file to inject.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlExtraResourcesBuilder AddScriptTag(Uri url)
     {
         return this.AddItem(new ExtraUrlResourceItem(url, ExtraUrlResourceType.ScriptTag));
@@ -61,7 +87,11 @@ public UrlExtraResourcesBuilder AddScriptTag(Uri url)
 
     #region caller specifies type
 
-    
+    /// <summary>
+    /// Adds a single extra resource with explicit type specification.
+    /// </summary>
+    /// <param name="item">Resource item with URL and type (LinkTag or ScriptTag).</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlExtraResourcesBuilder AddItem(ExtraUrlResourceItem item)
     {
         return this.AddItems(new[] { item ?? throw new ArgumentNullException(nameof(item)) });
@@ -75,13 +105,21 @@ public UrlExtraResourcesBuilder AddItem(ExtraUrlResourceItem item)
 
     #region link tags
 
-    
+    /// <summary>
+    /// Injects multiple CSS stylesheet link tags into the page.
+    /// </summary>
+    /// <param name="urls">Collection of CSS stylesheet URLs to inject.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlExtraResourcesBuilder AddLinkTags(IEnumerable<string> urls)
     {
         return this.AddLinkTags(urls.IfNullEmpty().Select(u => new Uri(u)));
     }
 
-    
+    /// <summary>
+    /// Injects multiple CSS stylesheet link tags into the page.
+    /// </summary>
+    /// <param name="urls">Collection of CSS stylesheet URIs to inject.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlExtraResourcesBuilder AddLinkTags(IEnumerable<Uri> urls)
     {
         return this.AddItems(
@@ -93,13 +131,21 @@ public UrlExtraResourcesBuilder AddLinkTags(IEnumerable<Uri> urls)
 
     #region script tags
 
-    
+    /// <summary>
+    /// Injects multiple JavaScript script tags into the page.
+    /// </summary>
+    /// <param name="urls">Collection of JavaScript file URLs to inject.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlExtraResourcesBuilder AddScriptTags(IEnumerable<string> urls)
     {
         return this.AddScriptTags(urls.IfNullEmpty().Select(u => new Uri(u)));
     }
 
-    
+    /// <summary>
+    /// Injects multiple JavaScript script tags into the page.
+    /// </summary>
+    /// <param name="urls">Collection of JavaScript file URIs to inject.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlExtraResourcesBuilder AddScriptTags(IEnumerable<Uri> urls)
     {
         return this.AddItems(
@@ -111,7 +157,11 @@ public UrlExtraResourcesBuilder AddScriptTags(IEnumerable<Uri> urls)
 
     #region caller specifies type
 
-    
+    /// <summary>
+    /// Adds multiple extra resources with explicit type specifications.
+    /// </summary>
+    /// <param name="items">Collection of resource items with URLs and types.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlExtraResourcesBuilder AddItems(IEnumerable<ExtraUrlResourceItem> items)
     {
         extraUrlResources.Items.AddRange(items.IfNullEmpty());

src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/UrlHeaderFooterBuilder.cs

@@ -17,31 +17,51 @@
 
 namespace Gotenberg.Sharp.API.Client.Domain.Builders.Faceted;
 
+/// <summary>
+/// Configures custom HTML header and footer for URL to PDF conversions.
+/// Header appears at the top of each page, footer at the bottom.
+/// </summary>
 public sealed class UrlHeaderFooterBuilder(HeaderFooterDocument headerFooterDocument)
 {
     #region header
 
-    
+    /// <summary>
+    /// Sets HTML content to appear at the top of every page.
+    /// </summary>
+    /// <param name="header">HTML content for the header.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlHeaderFooterBuilder SetHeader(ContentItem header)
     {
         headerFooterDocument.Header =
             header ?? throw new ArgumentNullException(nameof(header));
         return this;
     }
 
-    
+    /// <summary>
+    /// Sets HTML header content from a string.
+    /// </summary>
+    /// <param name="header">HTML string for the header.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlHeaderFooterBuilder SetHeader(string header)
     {
         return this.SetHeader(new ContentItem(header));
     }
 
-    
+    /// <summary>
+    /// Sets HTML header content from a byte array.
+    /// </summary>
+    /// <param name="header">HTML content as bytes.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlHeaderFooterBuilder SetHeader(byte[] header)
     {
         return this.SetHeader(new ContentItem(header));
     }
 
-    
+    /// <summary>
+    /// Sets HTML header content from a stream.
+    /// </summary>
+    /// <param name="header">Stream containing HTML content.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlHeaderFooterBuilder SetHeader(Stream header)
     {
         return this.SetHeader(new ContentItem(header));
@@ -51,27 +71,43 @@ public UrlHeaderFooterBuilder SetHeader(Stream header)
 
     #region footer
 
-    
+    /// <summary>
+    /// Sets HTML content to appear at the bottom of every page.
+    /// </summary>
+    /// <param name="footer">HTML content for the footer.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlHeaderFooterBuilder SetFooter(ContentItem footer)
     {
         headerFooterDocument.Footer =
             footer ?? throw new ArgumentNullException(nameof(footer));
         return this;
     }
 
-    
+    /// <summary>
+    /// Sets HTML footer content from a string.
+    /// </summary>
+    /// <param name="footer">HTML string for the footer.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlHeaderFooterBuilder SetFooter(string footer)
     {
         return this.SetFooter(new ContentItem(footer));
     }
 
-    
+    /// <summary>
+    /// Sets HTML footer content from a byte array.
+    /// </summary>
+    /// <param name="footer">HTML content as bytes.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlHeaderFooterBuilder SetFooter(byte[] footer)
     {
         return this.SetFooter(new ContentItem(footer));
     }
 
-    
+    /// <summary>
+    /// Sets HTML footer content from a stream.
+    /// </summary>
+    /// <param name="footer">Stream containing HTML content.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public UrlHeaderFooterBuilder SetFooter(Stream footer)
     {
         return this.SetFooter(new ContentItem(footer));