Add comprehensive XML documentation to public APIs #65
Conversation
This commit adds extensive XML documentation to improve IntelliSense for the public-facing builder API. Documentation follows Gotenberg terminology and focuses on clear, concise descriptions without examples to minimize IntelliSense verbosity. Completed: - All 5 fluent builder classes (HtmlRequestBuilder, UrlRequestBuilder, MergeBuilder, MergeOfficeBuilder, PdfConversionBuilder) - All 3 base builder classes (BaseBuilder, BaseChromiumBuilder, BaseMergeBuilder) - Critical faceted builders: DocumentBuilder and AssetBuilder Key improvements: - Explained Build() vs BuildAsync() distinction - Documented async method usage (when to use AddAsync*/WithAsync*) - Clarified AssetBuilder purpose and naming requirements - Added parameter descriptions and return types throughout - Documented Gotenberg module usage (Chromium, LibreOffice, PDF engines) - Added version requirements where applicable Remaining work: - ConfigBuilder, PagePropertyBuilder, HtmlConversionBehaviorBuilder, WebhookBuilder, UrlHeaderFooterBuilder, UrlExtraResourcesBuilder - GotenbergSharpClient methods (webhook, PDF conversion) - Enumerations (Margins values, DimensionUnitType, ExtraUrlResourceType) - Domain types (PageRanges format, ContentItem, ExtraUrlResourceItem) - Configuration classes and DI setup - Exception types - README updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
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>
Completes Phase 4 by documenting the previously undocumented methods in the GotenbergSharpClient class. Documented methods: - ConvertPdfDocumentsAsync (both overloads): PDF/A conversion and transformations - FireWebhookAndForgetAsync (all 3 overloads): Async webhook processing Key improvements: - Explained "fire and forget" webhook behavior (returns when Gotenberg accepts request, not when PDF is generated) - Documented that Gotenberg POSTs generated PDF to webhook URL - Added comprehensive exception documentation for all methods - Clarified difference between request acceptance and PDF generation completion - Added remarks explaining webhook use cases All public methods in GotenbergSharpClient now have complete documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Enhanced Phase 4 documentation by adding direct links to Gotenberg's official route documentation for each conversion method. Added seealso links for: - UrlToPdfAsync → Chromium route docs - HtmlToPdfAsync → Chromium route docs - MergePdfsAsync → Merge PDFs route docs - MergeOfficeDocsAsync → LibreOffice route docs - ConvertPdfDocumentsAsync → PDF/A conversion route docs Also improved summaries to be more descriptive and accurate. Users can now click directly to Gotenberg's documentation from IntelliSense to learn more about each conversion type. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Completes Phase 5 by documenting three critical enumerations with actual values that users need to know. Documented enumerations: - Margins: Added actual inch measurements for None (0"), Default (0.39"), Normal (1"), and Large (2") - DimensionUnitType: Documented all unit types with explanations and common use cases (Points, Pixels, Inches, Millimeters, Centimeters, Picas) - ExtraUrlResourceType: Clarified LinkTag (CSS) vs ScriptTag (JavaScript) with HTML tag examples Key improvements: - CRITICAL: Users can now see actual margin values in IntelliSense - Added context for when to use each unit type - Explained relationship to CSS and HTML tags for extra resources - All enum values now have clear, concise descriptions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Completes Phase 6 by documenting three key domain types used throughout
the client API.
Documented classes:
- PageRanges: Documented Chrome print format syntax ("1-5,8,11-13")
and clarified that empty collection means all pages
- ContentItem: Documented all three constructors with use cases
(byte[] for binary, string for HTML/text, Stream for files)
- ExtraUrlResourceItem: Documented resource injection for URL conversions
with CSS vs JavaScript distinction
Key improvements:
- CRITICAL: PageRanges.Create() now documents the expected format
- Explained when to use each ContentItem constructor
- Clarified ExtraUrlResourceItem usage for CSS/JS injection
- Added comprehensive exception documentation
- Documented public properties and methods
Users can now understand how to construct and use these types from
IntelliSense without referring to external documentation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
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>
Completes Phase 8 by documenting the GotenbergApiException class for proper error handling guidance. Documented class: - GotenbergApiException: Complete class, constructor, properties, and methods documentation Key improvements: - Explained when exception is thrown (Gotenberg error responses) - Documented all properties (StatusCode, RequestUri, ReasonPhrase) - Documented ToVerboseJson() for detailed error logging - Added parameter descriptions for ToVerboseJson options - Clarified exception contains both request and response details Users now have complete information for implementing error handling and logging in their applications. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Added section noting that all public APIs now include comprehensive XML documentation with IntelliSense support. Users can now discover: - Method descriptions with Gotenberg documentation links - Parameter explanations and valid ranges - Exception handling guidance - Usage notes and best practices This completes Phase 9 and the entire documentation improvement initiative. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
|
Caution Review failedThe pull request is closed. WalkthroughAdds builder-pattern APIs and overloads across URL/HTML/PDF/merge flows, expands asset/content handling and async configuration, introduces DI registration helpers, enriches exception details and retry settings, enforces absolute-URI validations in webhook/URL resources, and adds extensive XML docs plus a .gitignore and README docs update. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Dev as Developer
participant Builder as Builder (Url/Html/Pdf/Merge)
participant Client as GotenbergSharpClient
participant HTTP as HttpClient
participant Svc as Gotenberg API
Dev->>Builder: Configure (assets, headers, page ranges, etc.)
Dev->>Client: Call XToYAsync(builder)
Client->>Builder: Build()/BuildAsync()
Builder-->>Client: IApiRequest
Client->>HTTP: Send request
HTTP->>Svc: POST /convert/...
alt Success
Svc-->>HTTP: 200 PDF bytes
HTTP-->>Client: HttpResponseMessage
Client-->>Dev: Stream/byte[]
else Error
Svc-->>HTTP: 4xx/5xx + reason
HTTP-->>Client: HttpResponseMessage
Client->>Client: GotenbergApiException.Create(...)
Client-->>Dev: throw GotenbergApiException(StatusCode, ReasonPhrase, RequestUri)
end
sequenceDiagram
autonumber
participant App as Application
participant DI as IServiceCollection
participant Ext as TypedClientServiceCollectionExtensions
participant Prov as IServiceProvider
participant Http as HttpClientFactory
App->>Ext: AddGotenbergSharpClient(DI)
Ext->>DI: AddHttpClient(name, configure)
Ext->>DI: AddTypedClient<GotenbergSharpClient>()
note right of Ext #e6f7ff: Sets Timeout, BaseAddress,\nBasic Auth, decompression,\npolicy handler, handler lifetime
App->>Prov: BuildServiceProvider()
Prov->>Http: CreateClient(name)
Prov-->>App: GotenbergSharpClient
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@coderabbitai help |
ChatThere are 3 ways to chat with CodeRabbit:
CodeRabbit commands
Other keywords and placeholders
CodeRabbit configuration file (
|
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/Gotenberg.Sharp.Api.Client/Domain/Pages/PageRanges.cs (1)
82-95: Handle descending ranges instead of silently dropping them.Segments like "5-3" match the regex but currently fall through the
bounds[0] <= bounds[1]check and get ignored, so the caller unknowingly receives a range missing pages 3–5. Please treat those as invalid input and throw to surface the mistake instead of returning incomplete results.- if (bounds.Length == 2 && bounds[0] <= bounds[1]) - { - for (var i = bounds[0]; i <= bounds[1]; i++) - { - pages.Add(i); - } - } + if (bounds.Length == 2 && bounds[0] <= bounds[1]) + { + for (var i = bounds[0]; i <= bounds[1]; i++) + { + pages.Add(i); + } + } + else + { + throw new ArgumentOutOfRangeException( + nameof(input), + $"Invalid page range segment '{trimmed}'. Range start must be less than or equal to its end."); + }
🧹 Nitpick comments (1)
src/Gotenberg.Sharp.Api.Client/Extensions/TypedClientServiceCollectionExtensions.cs (1)
80-97: Guard the services parameter in the second overload.The first overload throws
ArgumentNullExceptionwhenservicesis null, but Line 80’s overload skips that guard. If someone callsservices.AddGotenbergSharpClient(...);with a null reference, we’ll hit aNullReferenceExceptionat runtime. Add the sameif (services == null) throw ...check for parity and clearer diagnostics.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (28)
.gitignore(1 hunks)README.md(1 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/BaseBuilder.cs(3 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/BaseChromiumBuilder.cs(4 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/BaseMergeBuilder.cs(2 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/AssetBuilder.cs(4 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/ConfigBuilder.cs(6 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/DocumentBuilder.cs(4 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/HtmlConversionBehaviorBuilder.cs(3 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/Margins.cs(1 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/UrlExtraResourcesBuilder.cs(6 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/UrlHeaderFooterBuilder.cs(2 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/WebhookBuilder.cs(4 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/HtmlRequestBuilder.cs(2 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/MergeBuilder.cs(1 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/MergeOfficeBuilder.cs(1 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/PdfConversionBuilder.cs(4 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Builders/UrlRequestBuilder.cs(5 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Dimensions/DimensionUnitType.cs(1 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Pages/PageRanges.cs(3 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Requests/Facets/ContentItem.cs(2 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Requests/Facets/UrlExtras/ExtraUrlResourceItem.cs(2 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Requests/Facets/UrlExtras/ExtraUrlResourceType.cs(1 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Settings/GotenbergSharpClientOptions.cs(1 hunks)src/Gotenberg.Sharp.Api.Client/Domain/Settings/RetryOptions.cs(1 hunks)src/Gotenberg.Sharp.Api.Client/Extensions/TypedClientServiceCollectionExtensions.cs(2 hunks)src/Gotenberg.Sharp.Api.Client/GotenbergSharpClient.cs(12 hunks)src/Gotenberg.Sharp.Api.Client/Infrastructure/GotenbergApiException.cs(3 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
README.md
43-43: Heading style
Expected: setext; Actual: atx
(MD003, heading-style)
🔇 Additional comments (19)
src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/Margins.cs (1)
18-41: Documentation update looks solid.The summaries clearly describe each margin preset and should greatly help IntelliSense consumers.
README.md (1)
43-49: LGTM! Clear and helpful documentation section.The new IntelliSense Documentation section effectively communicates the comprehensive XML documentation coverage and its benefits to library users. The enumerated list clearly outlines what developers can expect from IntelliSense.
Note: The markdownlint hint about heading style (MD003) is a stylistic preference (atx
##vs setext underline style). This is safe to ignore unless your project has specific markdown style guidelines.src/Gotenberg.Sharp.Api.Client/Domain/Requests/Facets/UrlExtras/ExtraUrlResourceType.cs (1)
20-38: LGTM! Clear and comprehensive enum documentation.The XML documentation effectively describes the enum's purpose and each member value, with proper HTML entity encoding for the tag examples. This will provide excellent IntelliSense support.
src/Gotenberg.Sharp.Api.Client/Domain/Settings/GotenbergSharpClientOptions.cs (1)
18-49: LGTM! Comprehensive configuration documentation.The XML documentation provides excellent guidance for developers configuring the client:
- Clear descriptions with default values stated
- Helpful remarks about configuration sources
- Practical context for each setting (e.g., when to increase timeout)
This will significantly improve the developer experience when configuring the client.
src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/UrlExtraResourcesBuilder.cs (1)
22-169: LGTM! Thorough builder documentation.The XML documentation comprehensively covers:
- Clear class-level description with practical use cases
- Helpful remarks distinguishing LinkTag and ScriptTag injection
- Complete documentation for all method overloads
- Exception documentation for error conditions
This will provide excellent IntelliSense guidance for developers injecting external resources.
src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/HtmlConversionBehaviorBuilder.cs (1)
20-105: LGTM! Enhanced builder documentation with practical context.The updated XML documentation effectively communicates:
- Comprehensive class-level overview of Chromium rendering configuration
- Improved AddAdditionalHeaders documentation with practical use cases (authentication, custom headers)
- Clear parameter descriptions and exception documentation
The practical examples (e.g., "Useful for authentication tokens") help developers understand when to use each method.
src/Gotenberg.Sharp.Api.Client/Domain/Builders/BaseBuilder.cs (1)
18-84: LGTM! Excellent documentation with defensive initialization improvement.The changes provide:
- Comprehensive XML documentation for the base builder class and all methods
- Clear guidance on when to use
Build()vsBuildAsync()- Proper exception documentation
The defensive initialization at line 43 (
this.Request.Config ??= new RequestConfig();) is a good safety measure that ensures the Config property is never null when using the Action-based overload, preventing potential NullReferenceExceptions.src/Gotenberg.Sharp.Api.Client/Domain/Requests/Facets/UrlExtras/ExtraUrlResourceItem.cs (2)
33-62: LGTM! Excellent addition of validation and convenience constructor.The changes provide:
- Convenient string-based constructor for easier API usage
- Enhanced validation in the Uri-based constructor:
- Null check for URL parameter (line 54)
- Absolute URI requirement (lines 55-56) - prevents relative URL errors
- ItemType validation using InvalidEnumArgumentException (lines 57-59)
- Comprehensive exception documentation
The absolute URI validation is particularly important for external resources, as Gotenberg needs fully qualified URLs to fetch CSS/JS files.
64-72: LGTM! Clear property documentation.The XML documentation for the Url and ItemType properties is concise and clearly explains their purpose, enhancing IntelliSense support.
src/Gotenberg.Sharp.Api.Client/Domain/Builders/BaseMergeBuilder.cs (1)
18-54: LGTM! Consistent builder pattern with comprehensive documentation.The changes provide:
- Clear class-level documentation explaining the merge builder's purpose
- New
WithAssetsandWithAsyncAssetsmethods that follow the consistent builder pattern used throughout the codebase- Proper null validation and defensive initialization (
this.Request.Assets ??= new AssetDictionary())- Comprehensive XML documentation with parameter descriptions and return value explanations
The fluent API additions align well with the broader builder pattern enhancements in this PR and provide a consistent developer experience.
src/Gotenberg.Sharp.Api.Client/Domain/Builders/PdfConversionBuilder.cs (1)
18-90: Documentation and asset initialization look solid.Nice job ensuring the asset dictionary is initialized in both sync and async flows—this keeps the builder resilient and matches the new XML docs.
src/Gotenberg.Sharp.Api.Client/Domain/Builders/HtmlRequestBuilder.cs (1)
18-64: Builder overloads integrate cleanly.The parameterless constructor plus the sync/async document configuration fit well with the existing builder flow. Everything here reads clean—no further action needed.
src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/WebhookBuilder.cs (1)
20-148: Webhook validation improvements look good.The absolute-URI validation and the expanded doc comments strengthen the builder without altering behavior.
src/Gotenberg.Sharp.Api.Client/Domain/Builders/BaseChromiumBuilder.cs (1)
18-128: Chromium builder enhancements are well put together.The new fluent entry points cover the major configuration areas and include the right null-guards. Looks ready to merge.
src/Gotenberg.Sharp.Api.Client/Domain/Builders/Faceted/DocumentBuilder.cs (5)
18-21: LGTM! Clear class-level documentation.The class summary effectively describes the builder's purpose and key configuration areas (body, header, footer) in a concise manner suitable for IntelliSense.
43-52: LGTM! Well-documented replacement for obsolete method.The new
SetContainsMarkdownmethod properly documents the Markdown handling behavior, and the obsoleteContainsMarkdownmethod correctly delegates to it for backwards compatibility.
54-94: LGTM! Clean overload pattern with helpful documentation.The SetBody overloads follow a clean pattern with the
ContentItembase method handling null validation, while convenience overloads forstring,byte[], andStreamdelegate appropriately. The documentation clearly distinguishes each overload's input type.Note: Line 56 documents this as "Required for all HTML/Markdown conversions" - while this is good guidance for users, the requirement isn't enforced at this builder level (likely validated downstream in the request pipeline).
100-140: LGTM! Consistent header overloads with clear optional status.The SetHeader overloads mirror the SetBody pattern and correctly document that headers are optional, appearing in the top margin area. The four overload variants provide convenient entry points for different content sources.
146-186: LGTM! Footer overloads complete the document configuration API.The SetFooter overloads follow the established pattern consistently, with clear documentation indicating they're optional and appear in the bottom margin. The implementation is correct and the documentation is IntelliSense-friendly.
Includes all changes since v2.8.1: - Configuration improvements - Comprehensive documentation (PR #65) - Examples conversion and bug fixes (PR #66) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 participant
Summary
This PR adds comprehensive XML documentation to all public-facing APIs in the GotenbergSharpApiClient library, providing rich IntelliSense support for users.
Changes
Documentation Coverage (20+ files)
Key Features
<seealso>links to official Gotenberg endpoint documentationImpact
Users will now have comprehensive IntelliSense documentation when using the library, improving discoverability and reducing the need to reference external documentation.
Testing
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
Summary by CodeRabbit
New Features
Bug Fixes
Documentation
Chores