Skip to content

Commit d065574

Browse files
Jabenclaude
andcommitted
Add comprehensive XML documentation to configuration and DI
Completes Phase 7 by documenting configuration options and dependency injection setup - critical for users getting started with the library. Documented classes: - TypedClientServiceCollectionExtensions: Both AddGotenbergSharpClient overloads with setup guidance and appsettings.json examples - GotenbergSharpClientOptions: All properties with defaults and use cases (TimeOut: 3min, ServiceUrl: localhost:3000, RetryPolicy, BasicAuth) - RetryOptions: All retry configuration properties with exponential backoff formula and defaults Key improvements: - CRITICAL: Users now know how to configure the client via DI - Documented all default values (TimeOut, ServiceUrl, RetryCount, etc.) - Explained exponential backoff formula: Math.Pow(BackoffPower, retryAttempt) - Clarified Docker Compose URL setup (http://gotenberg:3000) - Documented retry behavior (disabled by default, 3 retries when enabled) - Added appsettings.json section guidance This documentation is essential for first-time users setting up the client. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent d8612f3 commit d065574

3 files changed

Lines changed: 63 additions & 5 deletions

File tree

src/Gotenberg.Sharp.Api.Client/Domain/Settings/GotenbergSharpClientOptions.cs

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,37 @@
1515

1616
namespace Gotenberg.Sharp.API.Client.Domain.Settings;
1717

18+
/// <summary>
19+
/// Configuration options for GotenbergSharpClient.
20+
/// </summary>
21+
/// <remarks>
22+
/// Configure these options in appsettings.json under the "GotenbergSharpClient" section
23+
/// or programmatically using services.Configure&lt;GotenbergSharpClientOptions&gt;().
24+
/// </remarks>
1825
public class GotenbergSharpClientOptions
1926
{
27+
/// <summary>
28+
/// HTTP timeout for requests to Gotenberg. Default: 3 minutes.
29+
/// Increase this for large documents or complex conversions that may take longer to process.
30+
/// </summary>
2031
public TimeSpan TimeOut { get; set; } = TimeSpan.FromMinutes(3);
2132

33+
/// <summary>
34+
/// Base URL of the Gotenberg service. Default: http://localhost:3000.
35+
/// Set this to your Gotenberg instance URL (e.g., http://gotenberg:3000 in Docker Compose).
36+
/// </summary>
2237
public Uri ServiceUrl { get; set; } = new Uri("http://localhost:3000");
2338

2439
/// <summary>
25-
/// Convenience property for specifying a health check URL.
40+
/// Convenience property for specifying a health check URL. Default: http://localhost:3000/health.
2641
/// Note: This property is not currently used by the library.
2742
/// </summary>
2843
public Uri HealthCheckUrl { get; set; } = new Uri("http://localhost:3000/health");
2944

45+
/// <summary>
46+
/// Retry policy configuration for handling transient failures. Default: Disabled with 3 retries when enabled.
47+
/// Configure retry count, exponential backoff, and logging options.
48+
/// </summary>
3049
public RetryOptions RetryPolicy { get; set; } = new RetryOptions();
3150

3251
/// <summary>

src/Gotenberg.Sharp.Api.Client/Domain/Settings/RetryOptions.cs

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,33 @@
1515

1616
namespace Gotenberg.Sharp.API.Client.Domain.Settings;
1717

18+
/// <summary>
19+
/// Configuration options for retry behavior when requests to Gotenberg fail due to transient errors.
20+
/// </summary>
1821
public class RetryOptions
1922
{
23+
/// <summary>
24+
/// Enables or disables retry behavior. Default: false (disabled).
25+
/// When enabled, failed requests will be retried with exponential backoff.
26+
/// </summary>
2027
public bool Enabled { get; set; }
2128

29+
/// <summary>
30+
/// Number of retry attempts for failed requests. Default: 3.
31+
/// Only applies when Enabled is true.
32+
/// </summary>
2233
public int RetryCount { get; set; } = 3;
2334

2435
/// <summary>
25-
/// Configures the sleep duration provider with an exponential wait time between retries.
26-
/// E.G. sleepDurationProvider: retryCount => TimeSpan.FromSeconds(Math.Pow(retryOps.BackoffPower, retryCount))
36+
/// Exponential backoff power for calculating sleep duration between retries. Default: 1.5.
37+
/// Sleep duration is calculated as: TimeSpan.FromSeconds(Math.Pow(BackoffPower, retryAttempt)).
38+
/// Higher values result in longer waits between retries.
2739
/// </summary>
28-
2940
public double BackoffPower { get; set; } = 1.5;
3041

42+
/// <summary>
43+
/// Enables or disables logging of retry attempts. Default: true.
44+
/// When enabled, retry attempts and failures are logged for debugging.
45+
/// </summary>
3146
public bool LoggingEnabled { get; set; } = true;
3247
}

src/Gotenberg.Sharp.Api.Client/Extensions/TypedClientServiceCollectionExtensions.cs

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,22 @@
2525

2626
namespace Gotenberg.Sharp.API.Client.Extensions;
2727

28+
/// <summary>
29+
/// Extension methods for registering GotenbergSharpClient with dependency injection.
30+
/// </summary>
2831
public static class TypedClientServiceCollectionExtensions
2932
{
33+
/// <summary>
34+
/// Registers GotenbergSharpClient with dependency injection using configured options.
35+
/// Configure options via appsettings.json or by calling services.Configure&lt;GotenbergSharpClientOptions&gt;().
36+
/// </summary>
37+
/// <param name="services">The service collection.</param>
38+
/// <returns>An IHttpClientBuilder for further configuration.</returns>
39+
/// <exception cref="ArgumentNullException">Thrown when services is null.</exception>
40+
/// <remarks>
41+
/// This method configures the HttpClient with automatic compression, retry policies, and basic authentication if credentials are provided.
42+
/// Options should be configured in the "GotenbergSharpClient" section of appsettings.json or programmatically.
43+
/// </remarks>
3044
public static IHttpClientBuilder AddGotenbergSharpClient(
3145
this IServiceCollection services)
3246
{
@@ -51,7 +65,17 @@ public static IHttpClientBuilder AddGotenbergSharpClient(
5165
});
5266
}
5367

54-
68+
/// <summary>
69+
/// Registers GotenbergSharpClient with dependency injection using a custom HttpClient configuration.
70+
/// </summary>
71+
/// <param name="services">The service collection.</param>
72+
/// <param name="configureClient">Action to configure the HttpClient instance.</param>
73+
/// <returns>An IHttpClientBuilder for further configuration.</returns>
74+
/// <exception cref="ArgumentNullException">Thrown when configureClient is null.</exception>
75+
/// <remarks>
76+
/// This overload allows full control over HttpClient configuration. The client is configured with
77+
/// automatic compression, timeout handling, and exponential backoff retry policies.
78+
/// </remarks>
5579
public static IHttpClientBuilder AddGotenbergSharpClient(
5680
this IServiceCollection services,
5781
Action<IServiceProvider, HttpClient> configureClient)

0 commit comments

Comments
 (0)