docs: add a request-binder usage sample with a living catalog - #187
Merged
Conversation
Add FirstClassErrors.RequestBinder.Usage, a dedicated sample giving a complete, runnable picture of the request binder on a hotel-booking boundary: - BookingBinder binds a full request end-to-end: required/optional, raw and converted scalars, the value-type overloads, a nested object, lists of simple and of complex elements, the New and validating Create terminals, and collect-all aggregation. - BinderShowcase rounds out the remaining overloads and options: required lists, optional sections, a custom IArgumentNameProvider, custom structural codes, and the non-nullable value-type guard. - BookingEndpoint is a framework-agnostic call site rejoining the Outcome pipeline. - Every sample error is fully documented and localized (en, fr, es, de, sv). The sample has its own generated, snapshot-tested catalog in FirstClassErrors.GenDoc.UnitTests, and companion unit tests assert the collect-all order, envelope codes, and argument paths. This meets the intent of the issue (the binder exercised in living, generated documentation) with a sibling sample rather than by folding binder specifics into the core FirstClassErrors.Usage catalog. Refs: #154 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014QZMxXBeE7iXCLkaZshuFR
Reefact
force-pushed
the
claude/request-binder-usage-examples-yld421
branch
from
July 18, 2026 22:04
55fba57 to
1704813
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a dedicated
FirstClassErrors.RequestBinder.Usagesample that gives a complete, runnable picture of the request binder on a hotel-booking boundary, with its own generated, snapshot-tested error catalog. This meets the intent of #154 (the binder exercised in living, generated documentation) with a sibling sample rather than by folding binder specifics into the coreFirstClassErrors.Usagecatalog — see the rationale on the issue.Type of change
Changes
FirstClassErrors.RequestBinder.Usage(net8.0;net10.0), referencing the binder + core and dogfooding the analyzers:BookingBinder— a full request bound end-to-end: required/optional, raw and converted scalars, the value-type overloads, a nested object, lists of simple and of complex elements, theNewand validatingCreateterminals, and collect-all aggregation.BinderShowcase— the remaining overloads and options: required lists, optional sections, a customIArgumentNameProvider(snake_case), custom structural codes with symbolic branching, and the non-nullable value-type guard.BookingEndpoint— a framework-agnostic call site rejoining theOutcomepipeline.class;NightCount/RoomNumberarestruct, a deliberate consumer-side demonstration of the value-type overloads, documented in-code — the library's own value objects stay classes per CLAUDE.md) and three envelope errors, each fully documented and localized (en, fr, es, de, sv).FirstClassErrors.RequestBinder.Usage.UnitTestsasserting the collect-all order, envelope codes, and argument paths.FirstClassErrors.GenDoc.UnitTeststhat extracts and renders the sample's catalog (JSON / Markdown / HTML, single + split, localized ×4), giving the binder its own generated, snapshot-tested catalog.FirstClassErrors.sln; add a "Runnable examples" pointer to the English and French request-binder guides.Testing
dotnet build FirstClassErrors.slndotnet test FirstClassErrors.slnFirstClassErrors.Analyzers.UnitTests)Full solution builds warning-free on net8.0 and net10.0; the whole suite is green (1028 tests, including 14 new behavioural tests and 14 new snapshot tests). The existing
FirstClassErrors.Usagesnapshots are unchanged.Documentation
doc/updateddoc/handwritten/for-users/README.fr.md) updated if user-facing behavior changedThe request-binder guide gains a "Runnable examples" section in both the English (
RequestBinder.en.md) and French (RequestBinder.fr.md) versions. Every sample error is documented and localized in five languages.Architecture decisions
Proposed: ADR-____The sample illustrates decisions already recorded (ADR-0007, 0008, 0012, 0016, 0017) without changing, superseding, or contradicting any. Note: the sample is not wired into the CI living-catalog / release gate (
errors-baseline.json,gendoc-docs.yml --assemblies) — a deliberate scope boundary; its catalog is exercised by unit-test snapshots only.Related issues
Closes #154
🤖 Generated with Claude Code
Generated by Claude Code