Merge pull request #65 from ChangemakerStudios/feature/documentation-improvement

Add comprehensive XML documentation to public APIs

Author: Jaben

.gitignore

@@ -288,3 +288,4 @@ __pycache__/
 *.odx.cs
 *.xsd.cs
 
+settings.local.json

README.md

@@ -41,6 +41,13 @@ PM> Install-Package Gotenberg.Sharp.Api.Client
 
 *Note: Use v1.x nugets for Gotenberg v6.*
 
+## IntelliSense Documentation
+All public APIs include comprehensive XML documentation with clear descriptions, parameter details, and links to official Gotenberg documentation. IntelliSense provides:
+- Method descriptions with Gotenberg route documentation links
+- Parameter explanations and valid value ranges
+- Exception documentation for error handling
+- Usage notes and best practices
+
 ## AppSettings
 ```json
   "GotenbergSharpClient": {

src/Gotenberg.Sharp.Api.Client/Domain/Builders/BaseBuilder.cs

@@ -15,6 +15,11 @@
 
 namespace Gotenberg.Sharp.API.Client.Domain.Builders;
 
+/// <summary>
+/// Base class for all Gotenberg request builders. Provides core functionality for building and configuring requests.
+/// </summary>
+/// <typeparam name="TRequest">The type of request being built.</typeparam>
+/// <typeparam name="TBuilder">The concrete builder type for fluent interface chaining.</typeparam>
 public abstract class BaseBuilder<TRequest, TBuilder>(TRequest request)
     where TRequest : BuildRequestBase
     where TBuilder : BaseBuilder<TRequest, TBuilder>
@@ -26,6 +31,11 @@ public abstract class BaseBuilder<TRequest, TBuilder>(TRequest request)
 
     protected virtual TRequest Request { get; } = request;
 
+    /// <summary>
+    /// Configures request-level settings such as webhooks, page ranges, result filename, and trace ID.
+    /// </summary>
+    /// <param name="action">Configuration action for request settings.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public TBuilder ConfigureRequest(Action<ConfigBuilder> action)
     {
         if (action == null) throw new ArgumentNullException(nameof(action));
@@ -37,20 +47,35 @@ public TBuilder ConfigureRequest(Action<ConfigBuilder> action)
         return (TBuilder)this;
     }
 
+    /// <summary>
+    /// Sets pre-configured request settings.
+    /// </summary>
+    /// <param name="config">Pre-configured RequestConfig instance.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public TBuilder ConfigureRequest(RequestConfig config)
     {
         this.Request.Config = config ?? throw new ArgumentNullException(nameof(config));
 
         return (TBuilder)this;
     }
 
+    /// <summary>
+    /// Builds the request synchronously. Use when all content is already in memory (no async operations).
+    /// </summary>
+    /// <returns>The configured request ready to send to Gotenberg.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when async methods (AddAsync*, WithAsync*) were used. Use BuildAsync instead.</exception>
     public virtual TRequest Build()
     {
         if (this.BuildTasks.Any()) throw new InvalidOperationException(CallBuildAsyncErrorMessage);
 
         return this.Request;
     }
 
+    /// <summary>
+    /// Builds the request asynchronously. Use when loading content from streams, files, or using any AddAsync* or WithAsync* methods.
+    /// Safe to use even when no async operations were performed.
+    /// </summary>
+    /// <returns>The configured request ready to send to Gotenberg.</returns>
     public virtual async Task<TRequest> BuildAsync()
     {
         if (this.BuildTasks.Any()) await Task.WhenAll(this.BuildTasks).ConfigureAwait(false);

src/Gotenberg.Sharp.Api.Client/Domain/Builders/BaseChromiumBuilder.cs

@@ -15,6 +15,12 @@
 
 namespace Gotenberg.Sharp.API.Client.Domain.Builders;
 
+/// <summary>
+/// Base class for builders that use Gotenberg's Chromium module for HTML and URL to PDF conversions.
+/// Provides configuration for page properties, assets, and Chromium rendering behaviors.
+/// </summary>
+/// <typeparam name="TRequest">The type of Chromium-based request being built.</typeparam>
+/// <typeparam name="TBuilder">The concrete builder type for fluent interface chaining.</typeparam>
 public abstract class BaseChromiumBuilder<TRequest, TBuilder>(TRequest request)
     : BaseBuilder<TRequest, TBuilder>(request)
     where TRequest : ChromeRequest
@@ -41,6 +47,11 @@ public TBuilder WithDimensions(PageProperties pageProperties)
         return (TBuilder)this;
     }
 
+    /// <summary>
+    /// Configures page properties including size, margins, orientation, scale, and rendering options.
+    /// </summary>
+    /// <param name="action">Configuration action for page properties.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public TBuilder WithPageProperties(Action<PagePropertyBuilder> action)
     {
         if (action == null) throw new ArgumentNullException(nameof(action));
@@ -54,20 +65,36 @@ public TBuilder WithPageProperties(Action<PagePropertyBuilder> action)
         return (TBuilder)this;
     }
 
+    /// <summary>
+    /// Sets pre-configured page properties.
+    /// </summary>
+    /// <param name="pageProperties">Pre-configured PageProperties instance.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public TBuilder WithPageProperties(PageProperties pageProperties)
     {
         this.Request.PageProperties = pageProperties ?? throw new ArgumentNullException(nameof(pageProperties));
 
         return (TBuilder)this;
     }
 
+    /// <summary>
+    /// Adds embedded resources (images, fonts, CSS, JavaScript files) referenced by the HTML content.
+    /// The asset filename must match how it's referenced in your HTML.
+    /// </summary>
+    /// <param name="action">Configuration action for adding assets.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public TBuilder WithAssets(Action<AssetBuilder> action)
     {
         if (action == null) throw new ArgumentNullException(nameof(action));
         action(new AssetBuilder(this.Request.Assets ??= new AssetDictionary()));
         return (TBuilder)this;
     }
 
+    /// <summary>
+    /// Asynchronously adds embedded resources. Use when loading assets from streams or files.
+    /// </summary>
+    /// <param name="asyncAction">Async configuration action for adding assets.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public TBuilder WithAsyncAssets(Func<AssetBuilder, Task> asyncAction)
     {
         if (asyncAction == null) throw new ArgumentNullException(nameof(asyncAction));
@@ -76,13 +103,23 @@ public TBuilder WithAsyncAssets(Func<AssetBuilder, Task> asyncAction)
         return (TBuilder)this;
     }
 
+    /// <summary>
+    /// Configures Chromium rendering behaviors including wait delays, cookies, HTTP headers, metadata, PDF format, and accessibility options.
+    /// </summary>
+    /// <param name="action">Configuration action for conversion behaviors.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public TBuilder SetConversionBehaviors(Action<HtmlConversionBehaviorBuilder> action)
     {
         if (action == null) throw new ArgumentNullException(nameof(action));
         action(new HtmlConversionBehaviorBuilder(this.Request.ConversionBehaviors));
         return (TBuilder)this;
     }
 
+    /// <summary>
+    /// Sets pre-configured Chromium conversion behaviors.
+    /// </summary>
+    /// <param name="behaviors">Pre-configured HtmlConversionBehaviors instance.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public TBuilder SetConversionBehaviors(HtmlConversionBehaviors behaviors)
     {
         this.Request.ConversionBehaviors =

src/Gotenberg.Sharp.Api.Client/Domain/Builders/BaseMergeBuilder.cs

@@ -15,9 +15,21 @@
 
 namespace Gotenberg.Sharp.API.Client.Domain.Builders;
 
+/// <summary>
+/// Base class for builders that merge documents (PDFs or Office files) using Gotenberg's merge capabilities.
+/// Provides functionality for adding files to merge.
+/// </summary>
+/// <typeparam name="TRequest">The type of merge request being built.</typeparam>
+/// <typeparam name="TBuilder">The concrete builder type for fluent interface chaining.</typeparam>
 public abstract class BaseMergeBuilder<TRequest, TBuilder>(TRequest request) : BaseBuilder<TRequest, TBuilder>(request)
     where TRequest : BuildRequestBase where TBuilder : BaseMergeBuilder<TRequest, TBuilder>
 {
+    /// <summary>
+    /// Adds files to merge. For PDF merges, add PDF files. For Office merges, add Office documents (.docx, .xlsx, .pptx, etc.).
+    /// Files are merged in the order they are added.
+    /// </summary>
+    /// <param name="action">Configuration action for adding files.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public TBuilder WithAssets(Action<AssetBuilder> action)
     {
         if (action == null) throw new ArgumentNullException(nameof(action));
@@ -27,6 +39,11 @@ public TBuilder WithAssets(Action<AssetBuilder> action)
         return (TBuilder)this;
     }
 
+    /// <summary>
+    /// Asynchronously adds files to merge. Use when loading files from streams or the file system.
+    /// </summary>
+    /// <param name="asyncAction">Async configuration action for adding files.</param>
+    /// <returns>The builder instance for method chaining.</returns>
     public TBuilder WithAsyncAssets(Func<AssetBuilder, Task> asyncAction)
     {
         if (asyncAction == null) throw new ArgumentNullException(nameof(asyncAction));

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

@@ -15,6 +15,11 @@
 
 namespace Gotenberg.Sharp.API.Client.Domain.Builders.Faceted
 {
+    /// <summary>
+    /// Adds embedded resources (assets) to PDF conversion requests. Assets are files referenced by your HTML content
+    /// such as images, fonts, CSS stylesheets, and JavaScript files. The asset name must match exactly how it's
+    /// referenced in your HTML (e.g., "logo.png" for &lt;img src="logo.png"/&gt;).
+    /// </summary>
     public sealed class AssetBuilder
     {
         private readonly AssetDictionary _assets;
@@ -24,6 +29,13 @@ internal AssetBuilder(AssetDictionary assets)
             this._assets = assets;
         }
 
+        /// <summary>
+        /// Adds a single asset file. The name must be a relative filename with extension, matching the reference in your HTML.
+        /// </summary>
+        /// <param name="name">Filename as referenced in HTML (e.g., "styles.css", "logo.png"). Must include extension and not contain path separators.</param>
+        /// <param name="value">The file content.</param>
+        /// <returns>The builder instance for method chaining.</returns>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown when name is invalid (missing extension or contains path separators).</exception>
         public AssetBuilder AddItem(string name, ContentItem value)
         {
             // ReSharper disable once ComplexConditionExpression
@@ -39,16 +51,39 @@ public AssetBuilder AddItem(string name, ContentItem value)
             return this;
         }
 
+        /// <summary>
+        /// Adds a single asset from string content (typically for text files like CSS or JavaScript).
+        /// </summary>
+        /// <param name="name">Filename as referenced in HTML.</param>
+        /// <param name="value">File content as string.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItem(string name, string value) => AddItem(name, new ContentItem(value));
 
+        /// <summary>
+        /// Adds a single asset from byte array (typically for binary files like images or fonts).
+        /// </summary>
+        /// <param name="name">Filename as referenced in HTML.</param>
+        /// <param name="value">File content as bytes.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItem(string name, byte[] value) => AddItem(name, new ContentItem(value));
 
+        /// <summary>
+        /// Adds a single asset from a stream.
+        /// </summary>
+        /// <param name="name">Filename as referenced in HTML.</param>
+        /// <param name="value">Stream containing file content.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItem(string name, Stream value) => AddItem(name, new ContentItem(value));
 
         #region 'n' assets
 
         #region from dictionaries
 
+        /// <summary>
+        /// Adds multiple assets from a dictionary. Useful for adding several files at once.
+        /// </summary>
+        /// <param name="items">Dictionary of filename to content mappings.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItems(Dictionary<string, ContentItem>? items)
         {
             foreach (var item in items.IfNullEmpty())
@@ -59,35 +94,70 @@ public AssetBuilder AddItems(Dictionary<string, ContentItem>? items)
             return this;
         }
 
+        /// <summary>
+        /// Adds multiple assets from a dictionary with string content.
+        /// </summary>
+        /// <param name="assets">Dictionary of filename to string content mappings.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItems(Dictionary<string, string>? assets) =>
             AddItems(assets?.ToDictionary(a => a.Key, a => new ContentItem(a.Value)));
 
+        /// <summary>
+        /// Adds multiple assets from a dictionary with byte array content.
+        /// </summary>
+        /// <param name="assets">Dictionary of filename to byte array mappings.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItems(Dictionary<string, byte[]>? assets) =>
             AddItems(assets?.ToDictionary(a => a.Key, a => new ContentItem(a.Value)));
 
+        /// <summary>
+        /// Adds multiple assets from a dictionary with stream content.
+        /// </summary>
+        /// <param name="assets">Dictionary of filename to stream mappings.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItems(Dictionary<string, Stream>? assets) =>
             AddItems(assets?.ToDictionary(a => a.Key, a => new ContentItem(a.Value)));
 
         #endregion
 
         #region from KVP enumerables
 
+        /// <summary>
+        /// Adds multiple assets from a key-value pair enumerable.
+        /// </summary>
+        /// <param name="assets">Enumerable of filename to content mappings.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItems(IEnumerable<KeyValuePair<string, ContentItem>> assets) =>
             AddItems(
                 new Dictionary<string, ContentItem>(
                     assets?.ToDictionary(a => a.Key, a => a.Value) ?? throw new ArgumentNullException(nameof(assets))));
 
+        /// <summary>
+        /// Adds multiple assets from a key-value pair enumerable with string content.
+        /// </summary>
+        /// <param name="assets">Enumerable of filename to string content mappings.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItems(IEnumerable<KeyValuePair<string, string>> assets) =>
             AddItems(
                 new Dictionary<string, ContentItem>(
                     assets?.ToDictionary(a => a.Key, a => new ContentItem(a.Value))
                     ?? throw new ArgumentNullException(nameof(assets))));
 
+        /// <summary>
+        /// Adds multiple assets from a key-value pair enumerable with byte array content.
+        /// </summary>
+        /// <param name="assets">Enumerable of filename to byte array mappings.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItems(IEnumerable<KeyValuePair<string, byte[]>> assets) =>
             AddItems(
                 assets?.ToDictionary(a => a.Key, a => new ContentItem(a.Value))
                 ?? throw new ArgumentNullException(nameof(assets)));
 
+        /// <summary>
+        /// Adds multiple assets from a key-value pair enumerable with stream content.
+        /// </summary>
+        /// <param name="assets">Enumerable of filename to stream mappings.</param>
+        /// <returns>The builder instance for method chaining.</returns>
         public AssetBuilder AddItems(IEnumerable<KeyValuePair<string, Stream>> assets) =>
             AddItems(
                 assets?.ToDictionary(s => s.Key, a => new ContentItem(a.Value))