From c56e095b534f318f2e9e9211e30bb5858789292c Mon Sep 17 00:00:00 2001 From: Sylvain Aurat Date: Tue, 14 Jul 2026 17:32:28 +0200 Subject: [PATCH 01/10] docs: make library comparison concrete and neutral --- doc/ComparisonWithOtherLibraries.en.md | 196 ++++++++++++++++++------- 1 file changed, 140 insertions(+), 56 deletions(-) diff --git a/doc/ComparisonWithOtherLibraries.en.md b/doc/ComparisonWithOtherLibraries.en.md index 487592f..f2f5812 100644 --- a/doc/ComparisonWithOtherLibraries.en.md +++ b/doc/ComparisonWithOtherLibraries.en.md @@ -3,93 +3,177 @@ 🌍 **Languages:** 🇬🇧 English (this file) | đŸ‡«đŸ‡· [Français](./ComparisonWithOtherLibraries.fr.md) -[ErrorOr](https://github.com/amantinband/error-or) and [FluentResults](https://github.com/altmann/FluentResults) are excellent, mature libraries. If your goal is a lightweight *Result* type — returning errors as values instead of throwing — they are focused, well-adopted choices for exactly that. +> Comparison reviewed on **2026-07-14** against the public documentation of [ErrorOr](https://github.com/error-or/error-or) and [FluentResults](https://github.com/altmann/FluentResults). Their APIs and goals may evolve; verify their current documentation before making a long-term choice. -FirstClassErrors answers a **different question**. It is not primarily a *Result* library: it is a way to make errors **first-class, documented and diagnosable knowledge** about your system — errors you can *carry* as values **or** *throw* as exceptions, using one and the same model. +ErrorOr, FluentResults, and FirstClassErrors all help applications represent failure explicitly, but they optimize for different primary goals. + +This page does not rank them. It shows the same situation through three different centres of gravity so you can choose the model that best matches your system. -This page highlights what FirstClassErrors does differently. +## The scenario -## 🎯 A different centre of gravity +A payment provider refuses an authorization request. The application needs to: -| Library | The question it answers | -|---|---| -| **ErrorOr** | *How do I return one or more errors as a value instead of throwing?* | -| **FluentResults** | *How do I return a result carrying errors, successes and causal reasons?* | -| **FirstClassErrors** | *How do I turn errors into documented, diagnosable knowledge — and move them through my system however each layer needs?* | +- return a failure without crashing the process; +- expose a safe message to the caller; +- preserve an internal diagnostic message; +- keep a stable code for logs and support; +- possibly document how the failure should be investigated. -For ErrorOr and FluentResults, the **error is a payload of the result type**. For FirstClassErrors, the **error is the model**, and the result type (`Outcome`) is just one of several ways to transport it. +## ErrorOr: a discriminated union of value or errors -## đŸ§© One error model, three transports +ErrorOr centres the API on `ErrorOr`, which carries either a successful value or one or more errors. + +```csharp +private static readonly Error PaymentDeclined = Error.Failure( + code: "PAYMENT_DECLINED", + description: "The payment was declined."); + +public ErrorOr Pay(Order order) +{ + if (provider.Declines(order)) + { + return PaymentDeclined; + } -The `Error` model is decoupled from the way it travels. The *same* error can be: + return new Receipt(order.Id); +} +``` -- kept as **data** — an `Error` value you inspect, log or enrich; -- **thrown** — turned into a typed exception with `error.ToException()`, then caught and routed by type; -- **carried** — wrapped in an `Outcome` / `Outcome` and composed without throwing. +A caller can inspect, match, switch on, or compose the result. Built-in error types and metadata support categorization and application-specific information. -Bridges connect all three, so you are never locked into one style. You can *carry* errors inside your domain and *throw* them at a boundary — with **the same error object**, no re-modeling in between. +Choose this style when the central need is an ergonomic value-or-errors flow, especially when multiple validation errors or HTTP-oriented result handling are important. -ErrorOr and FluentResults are, by design, *errors-as-values only*: the error is coupled to the result type and the model deliberately avoids throwing. FirstClassErrors treats the exception path as a **first-class citizen** alongside the value path. +## FluentResults: a result with reasons and metadata -## 📖 Errors that carry meaning, not just an identifier +FluentResults centres the API on `Result` and `Result`. Failures carry one or more reasons, and reasons can contain metadata and nested causes. -An ErrorOr `Error` is a code, a description, a `Type` and a metadata bag. A FluentResults error is a message with metadata and nested reasons. That is enough to *handle* an error at runtime. +```csharp +public Result Pay(Order order) +{ + if (provider.Declines(order)) + { + return Result.Fail( + new Error("The payment was declined.") + .WithMetadata("Code", "PAYMENT_DECLINED")); + } -A FirstClassErrors error is described for **humans**: a title, a plain-language explanation, the **business rule** that was violated, and representative examples. The error stops being a technical token and becomes something a developer — or a support engineer — can actually *understand*. + return Result.Ok(new Receipt(order.Id)); +} +``` -## 🔎 Diagnostics built for investigation +The reasons model is useful when an application needs rich success and failure chains, metadata, and configurable result handling. -Where the others *classify* an error (an `ErrorType` enum, a metadata entry), FirstClassErrors lets an error declare **how to investigate it**: +Choose this style when the result and its reason graph are the primary abstraction you want to compose. -- one or more **possible causes**; -- the likely **origin** of each one (`Internal`, `External`, `InternalOrExternal`); -- an **analysis lead** — where to start looking. +## FirstClassErrors: an error model with several transports -This turns the error from *"what failed"* into *"what probably went wrong, and where to begin"* — the difference between an error message and an on-call runbook. +FirstClassErrors centres the API on the error itself. `Outcome` is one transport, and `ToException()` is another. -## 📚 Documentation generated from your code +```csharp +internal static DomainError PaymentDeclined( + string providerCode, + Guid paymentId) +{ + return DomainError.Create( + Code.PaymentDeclined, + diagnosticMessage: + $"Provider refused payment {paymentId} with code {providerCode}.", + configureContext: context => + context.Add(ContextKey.PaymentId, paymentId)) + .WithPublicMessage( + shortMessage: "The payment was declined.", + detailedMessage: + "Use another payment method or contact your bank."); +} +``` -Because errors are described in code with the `DescribeError` DSL, their documentation is **generated automatically into an error catalog** — a living reference that stays in sync with the code and is ready for developers and support teams alike. +```csharp +public Outcome Pay(Order order) +{ + if (provider.Declines(order, out string providerCode)) + { + return Outcome.Failure( + PaymentError.PaymentDeclined(providerCode, order.PaymentId)); + } -Neither ErrorOr nor FluentResults produces documentation from your error definitions; the description lives, at best, in scattered strings and metadata. Here, **documenting an error and defining it are the same act**. + return Outcome.Success(new Receipt(order.Id)); +} +``` -## đŸŽšïž Fluent where it helps, plain code where it doesn't +The same factory can also feed exception flow: -`Outcome` offers a fluent pipeline (`Then`, `To`, `Recover`, `Finally`) to compose steps without throwing — use it when it genuinely makes the flow clearer. +```csharp +throw PaymentError + .PaymentDeclined(providerCode, paymentId) + .ToException(); +``` -But that pipeline is an **optional transport, not the centre of gravity**. When a plain `if` returning a well-named domain error reads closer to the business, FirstClassErrors encourages you to *write that instead*. Your error handling stays at **business altitude**; you are never pushed into long fluent chains just to remain "idiomatic". +The error can additionally be linked to structured documentation describing its title, rule, possible causes, analysis leads, and examples. The generated catalog and catalog-versioning workflow are part of the library's intended use. -Railway-oriented result libraries tend to make the fluent pipeline the primary idiom. Here, the pipeline serves the error — not the other way around. +Choose this style when the error definition itself must remain stable, documented, diagnosable, and independent from whether a caller returns or throws it. -## đŸ›ïž Architecture- and operations-aware +## What changes between the approaches? -The model speaks the language of layered / hexagonal design out of the box: +| Concern | ErrorOr | FluentResults | FirstClassErrors | +| --- | --- | --- | --- | +| Primary abstraction | value or errors | result with reasons | structured error | +| Value-based failure flow | central | central | available through `Outcome` | +| Multiple errors or reasons | built in | built in | modeled through inner errors or application aggregation | +| Metadata / occurrence facts | metadata | metadata | typed `ErrorContext` | +| Dedicated public vs internal messages | application-defined | application-defined | explicit in the core model | +| Typed exception transport from the same error | not the primary model | not the primary model | built in through `ToException()` | +| Domain / infrastructure / port taxonomy | application-defined | application-defined | built in | +| Transience and interaction direction | application-defined | application-defined | built in for infrastructure errors | +| Generated human documentation | outside the library's main scope | outside the library's main scope | built in | +| Catalog compatibility checks | outside the library's main scope | outside the library's main scope | built in | -- a taxonomy of `DomainError`, `InfrastructureError`, and primary / secondary **port** errors; -- infrastructure concerns such as `Transience` (transient / non-transient) and `InteractionDirection` (incoming / outgoing); -- an **occurrence identity** on every error — a unique `InstanceId` and a UTC timestamp — to correlate logs and diagnostic events. +“Application-defined” or “outside the main scope” does not mean impossible. It means the concern is not the library's central abstraction and may be implemented by application conventions or surrounding tooling. -ErrorOr and FluentResults are deliberately architecture-agnostic and keep the error lightweight; these concepts are simply outside their scope. +## Decision guide -## 📊 At a glance +Choose **ErrorOr** when: -| | FirstClassErrors | ErrorOr | FluentResults | -|---|:---:|:---:|:---:| -| Return errors as values (railway style) | ✅ (optional) | ✅ | ✅ | -| Throw the *same* error as a typed exception | ✅ | ➖ | ➖ | -| Human-facing error model (title, business rule, explanation) | ✅ | ➖ | ➖ | -| Diagnostics: cause + origin + analysis lead | ✅ | ➖ | ➖ | -| Documentation generated from the code | ✅ | ➖ | ➖ | -| Architecture taxonomy (domain / infrastructure / port) | ✅ | ➖ | ➖ | -| Per-occurrence identity (id + timestamp) | ✅ | ➖ | ➖ | -| Fluent pipeline | Optional, by design | Central | Central | +- you primarily want a concise `T`-or-errors union; +- multiple validation errors are common; +- matching and functional composition are the main interaction style; +- a lightweight error representation is sufficient. -*➖ means "not a goal of that library", not "done badly": ErrorOr and FluentResults are focused on being lean result types.* +Choose **FluentResults** when: -## 🧭 Which one should you pick? +- you want both success and failure reasons; +- nested reason chains and metadata are central; +- the result graph itself is the model you want to enrich and compose. -- Reach for **ErrorOr** when you want a tiny, ergonomic result type with clean, HTTP-friendly error categorization. -- Reach for **FluentResults** when you want a result carrying rich reason chains and metadata. -- Reach for **FirstClassErrors** when you want your errors to be **documented, diagnosable knowledge** — described once in code, carried as values or thrown as exceptions, and turned into a catalog your whole team can rely on. +Choose **FirstClassErrors** when: + +- errors are durable concepts used by developers, support, operations, or clients; +- public and diagnostic messages must have explicit audiences; +- the same error must travel as data, an outcome, or an exception; +- domain and infrastructure failures require different operational meaning; +- generated documentation and compatibility checks are part of the requirement. -They are not really competing for the same job: the first two make errors easy to *return*; FirstClassErrors makes them easy to *understand, support and document*. +## A combination may also be valid + +These choices are not always exclusive. An application may use a general-purpose result library at some boundaries while keeping a separate documented error catalog. + +Before combining models, decide which type owns the stable error identity. Duplicating codes, messages, metadata, and mappings across two competing error models usually creates more work than it saves. + +## Questions to ask before choosing + +1. Is the primary problem **control flow**, **reason composition**, or **shared error knowledge**? +2. Must one error definition support both return and exception paths? +3. Who consumes the error model: only code, or also support and operations? +4. Are stable codes and context keys treated as a versioned contract? +5. Is generated documentation a requirement or an external concern? +6. Does the application need built-in domain and infrastructure semantics? +7. How much convention are you prepared to build around a smaller result type? + +The best choice is the smallest model that covers the real requirements without forcing the application to recreate its missing semantics elsewhere. + +--- + + + +--- \ No newline at end of file From 98221d552783448df1b4bf2f1c70c95ac1d0dfcd Mon Sep 17 00:00:00 2001 From: Sylvain Aurat Date: Tue, 14 Jul 2026 17:33:41 +0200 Subject: [PATCH 02/10] docs: make library comparison concrete and neutral --- doc/ComparisonWithOtherLibraries.fr.md | 198 ++++++++++++++++++------- 1 file changed, 141 insertions(+), 57 deletions(-) diff --git a/doc/ComparisonWithOtherLibraries.fr.md b/doc/ComparisonWithOtherLibraries.fr.md index 354458e..b816c50 100644 --- a/doc/ComparisonWithOtherLibraries.fr.md +++ b/doc/ComparisonWithOtherLibraries.fr.md @@ -1,95 +1,179 @@ # Comparaison avec les librairies de gestion d’erreurs -🌍 **Langues:** +🌍 **Langues :** 🇬🇧 [English](./ComparisonWithOtherLibraries.en.md) | đŸ‡«đŸ‡· Français (ce fichier) -[ErrorOr](https://github.com/amantinband/error-or) et [FluentResults](https://github.com/altmann/FluentResults) sont d’excellentes librairies, matures. Si votre objectif est un type *Result* lĂ©ger — retourner les erreurs comme des valeurs plutĂŽt que de les lever — ce sont des choix ciblĂ©s et largement adoptĂ©s, faits exactement pour ça. +> Comparaison revue le **14 juillet 2026** Ă  partir des documentations publiques d’[ErrorOr](https://github.com/error-or/error-or) et de [FluentResults](https://github.com/altmann/FluentResults). Leurs API et leurs objectifs peuvent Ă©voluer : vĂ©rifiez leur documentation actuelle avant un choix Ă  long terme. -FirstClassErrors rĂ©pond Ă  une **question diffĂ©rente**. Ce n’est pas d’abord une librairie *Result* : c’est une maniĂšre de faire des erreurs une **connaissance de premiĂšre classe, documentĂ©e et diagnosticable** sur votre systĂšme — des erreurs que vous pouvez *transporter* comme valeurs **ou** *lever* comme exceptions, avec un seul et mĂȘme modĂšle. +ErrorOr, FluentResults et FirstClassErrors permettent toutes de reprĂ©senter explicitement un Ă©chec, mais elles optimisent des besoins principaux diffĂ©rents. -Cette page met en avant ce que FirstClassErrors fait diffĂ©remment. +Cette page ne les classe pas. Elle montre une mĂȘme situation Ă  travers trois centres de gravitĂ© afin de choisir le modĂšle qui correspond rĂ©ellement au systĂšme. -## 🎯 Un centre de gravitĂ© diffĂ©rent +## Le scĂ©nario -| Librairie | La question Ă  laquelle elle rĂ©pond | -|---|---| -| **ErrorOr** | *Comment retourner une ou plusieurs erreurs comme valeur au lieu de les lever ?* | -| **FluentResults** | *Comment retourner un rĂ©sultat portant erreurs, succĂšs et raisons causales ?* | -| **FirstClassErrors** | *Comment transformer les erreurs en connaissance documentĂ©e et diagnosticable — et les faire circuler selon les besoins de chaque couche ?* | +Un fournisseur de paiement refuse une demande d’autorisation. L’application doit : -Pour ErrorOr et FluentResults, l’**erreur est une charge utile du type rĂ©sultat**. Pour FirstClassErrors, l’**erreur est le modĂšle**, et le type rĂ©sultat (`Outcome`) n’est que l’une des façons de la transporter. +- retourner un Ă©chec sans faire planter le processus ; +- exposer un message sĂ»r Ă  l’appelant ; +- conserver un message de diagnostic interne ; +- garder un code stable pour les logs et le support ; +- Ă©ventuellement documenter la maniĂšre d’investiguer cet Ă©chec. -## đŸ§© Un modĂšle d’erreur, trois transports +## ErrorOr : une union discriminĂ©e entre valeur et erreurs -Le modĂšle `Error` est dĂ©couplĂ© de la maniĂšre dont il voyage. La *mĂȘme* erreur peut ĂȘtre : +ErrorOr place `ErrorOr` au centre de son API. Ce type porte soit une valeur de succĂšs, soit une ou plusieurs erreurs. -- conservĂ©e comme **donnĂ©e** — une valeur `Error` que vous inspectez, journalisez ou enrichissez ; -- **levĂ©e** — transformĂ©e en exception typĂ©e via `error.ToException()`, puis attrapĂ©e et routĂ©e par type ; -- **transportĂ©e** — encapsulĂ©e dans un `Outcome` / `Outcome` et composĂ©e sans lever. +```csharp +private static readonly Error PaymentDeclined = Error.Failure( + code: "PAYMENT_DECLINED", + description: "The payment was declined."); -Des passerelles relient les trois : vous n’ĂȘtes jamais enfermĂ© dans un style. Vous pouvez *transporter* les erreurs dans votre domaine et les *lever* Ă  une frontiĂšre — avec **le mĂȘme objet erreur**, sans re-modĂ©lisation entre les deux. +public ErrorOr Pay(Order order) +{ + if (provider.Declines(order)) + { + return PaymentDeclined; + } -ErrorOr et FluentResults sont, par conception, *uniquement erreurs-comme-valeurs* : l’erreur est soudĂ©e au type rĂ©sultat et le modĂšle Ă©vite dĂ©libĂ©rĂ©ment de lever. FirstClassErrors traite le chemin exception comme une **citoyenne de premiĂšre classe**, au mĂȘme titre que le chemin valeur. + return new Receipt(order.Id); +} +``` -## 📖 Des erreurs qui portent du sens, pas seulement un identifiant +L’appelant peut inspecter, faire un `Match`, un `Switch` ou composer le rĂ©sultat. Les types d’erreurs intĂ©grĂ©s et les mĂ©tadonnĂ©es permettent de catĂ©goriser l’échec et d’ajouter des informations propres Ă  l’application. -Une `Error` d’ErrorOr, c’est un code, une description, un `Type` et un sac de mĂ©tadonnĂ©es. Une erreur FluentResults, c’est un message avec mĂ©tadonnĂ©es et raisons imbriquĂ©es. C’est suffisant pour *traiter* une erreur au runtime. +Choisissez cette approche lorsque le besoin central est un flux ergonomique « valeur ou erreurs », notamment lorsque plusieurs erreurs de validation ou une intĂ©gration HTTP orientĂ©e rĂ©sultat sont importantes. -Une erreur FirstClassErrors est dĂ©crite pour des **humains** : un titre, une explication en langage clair, la **rĂšgle mĂ©tier** violĂ©e et des exemples reprĂ©sentatifs. L’erreur cesse d’ĂȘtre un jeton technique pour devenir quelque chose qu’un dĂ©veloppeur — ou un ingĂ©nieur support — peut rĂ©ellement *comprendre*. +## FluentResults : un rĂ©sultat portant des raisons et des mĂ©tadonnĂ©es -## 🔎 Des diagnostics faits pour l’investigation +FluentResults place `Result` et `Result` au centre de son API. Les Ă©checs portent une ou plusieurs raisons, auxquelles peuvent ĂȘtre associĂ©s des mĂ©tadonnĂ©es et des causes imbriquĂ©es. -LĂ  oĂč les autres *classifient* une erreur (une enum `ErrorType`, une entrĂ©e de mĂ©tadonnĂ©es), FirstClassErrors permet Ă  une erreur de dĂ©clarer **comment l’investiguer** : +```csharp +public Result Pay(Order order) +{ + if (provider.Declines(order)) + { + return Result.Fail( + new Error("The payment was declined.") + .WithMetadata("Code", "PAYMENT_DECLINED")); + } -- une ou plusieurs **causes probables** ; -- l’**origine** probable de chacune (`Internal`, `External`, `InternalOrExternal`) ; -- une **piste d’analyse** — par oĂč commencer. + return Result.Ok(new Receipt(order.Id)); +} +``` -L’erreur passe ainsi de *« ce qui a Ă©chouĂ© »* Ă  *« ce qui a probablement mal tournĂ©, et par oĂč commencer »* — la diffĂ©rence entre un message d’erreur et un runbook d’astreinte. +Le modĂšle de raisons est utile lorsqu’une application a besoin de chaĂźnes riches de succĂšs et d’échecs, de mĂ©tadonnĂ©es et d’une gestion configurable des rĂ©sultats. -## 📚 Une documentation gĂ©nĂ©rĂ©e depuis votre code +Choisissez cette approche lorsque le rĂ©sultat et son graphe de raisons sont l’abstraction principale que vous souhaitez enrichir et composer. -Parce que les erreurs sont dĂ©crites dans le code avec le DSL `DescribeError`, leur documentation est **gĂ©nĂ©rĂ©e automatiquement sous forme de catalogue d’erreurs** — une rĂ©fĂ©rence vivante qui reste synchronisĂ©e avec le code, prĂȘte pour les dĂ©veloppeurs comme pour les Ă©quipes support. +## FirstClassErrors : un modĂšle d’erreur avec plusieurs transports -Ni ErrorOr ni FluentResults ne produisent de documentation Ă  partir de vos dĂ©finitions d’erreurs ; la description vit, au mieux, dans des chaĂźnes et des mĂ©tadonnĂ©es Ă©parpillĂ©es. Ici, **documenter une erreur et la dĂ©finir sont un seul et mĂȘme geste**. +FirstClassErrors place l’erreur elle-mĂȘme au centre. `Outcome` est un transport possible ; `ToException()` en est un autre. -## đŸŽšïž Le fluent lĂ  oĂč il aide, du code simple lĂ  oĂč il gĂȘne +```csharp +internal static DomainError PaymentDeclined( + string providerCode, + Guid paymentId) +{ + return DomainError.Create( + Code.PaymentDeclined, + diagnosticMessage: + $"Provider refused payment {paymentId} with code {providerCode}.", + configureContext: context => + context.Add(ContextKey.PaymentId, paymentId)) + .WithPublicMessage( + shortMessage: "The payment was declined.", + detailedMessage: + "Use another payment method or contact your bank."); +} +``` -`Outcome` offre un pipeline fluent (`Then`, `To`, `Recover`, `Finally`) pour composer des Ă©tapes sans lever — utilisez-le quand il rend vraiment le flux plus clair. +```csharp +public Outcome Pay(Order order) +{ + if (provider.Declines(order, out string providerCode)) + { + return Outcome.Failure( + PaymentError.PaymentDeclined(providerCode, order.PaymentId)); + } -Mais ce pipeline est un **transport optionnel, pas le centre de gravitĂ©**. Quand un simple `if` retournant une erreur de domaine bien nommĂ©e lit plus prĂšs du mĂ©tier, FirstClassErrors vous encourage Ă  *Ă©crire ça Ă  la place*. Votre gestion d’erreurs reste Ă  **hauteur mĂ©tier** ; vous n’ĂȘtes jamais poussĂ© vers de longues chaĂźnes fluent juste pour rester « idiomatique ». + return Outcome.Success(new Receipt(order.Id)); +} +``` -Les librairies *Result* orientĂ©es railway tendent Ă  faire du pipeline fluent l’idiome principal. Ici, le pipeline sert l’erreur — pas l’inverse. +La mĂȘme factory peut aussi alimenter un flux par exception : -## đŸ›ïž Consciente de l’architecture et de l’exploitation +```csharp +throw PaymentError + .PaymentDeclined(providerCode, paymentId) + .ToException(); +``` -Le modĂšle parle nativement le langage de la conception en couches / hexagonale : +L’erreur peut en outre ĂȘtre liĂ©e Ă  une documentation structurĂ©e dĂ©crivant son titre, sa rĂšgle, ses causes possibles, ses pistes d’analyse et ses exemples. Le catalogue gĂ©nĂ©rĂ© et son workflow de versionnage font partie de l’usage prĂ©vu de la librairie. -- une taxonomie de `DomainError`, `InfrastructureError`, et d’erreurs de **port** primaire / secondaire ; -- des prĂ©occupations d’infrastructure comme `Transience` (transitoire / non transitoire) et `InteractionDirection` (entrant / sortant) ; -- une **identitĂ© d’occurrence** sur chaque erreur — un `InstanceId` unique et un horodatage UTC — pour corrĂ©ler journaux et Ă©vĂšnements de diagnostic. +Choisissez cette approche lorsque la dĂ©finition de l’erreur doit rester stable, documentĂ©e, diagnosticable et indĂ©pendante du fait qu’un appelant la retourne ou la lĂšve. -ErrorOr et FluentResults sont dĂ©libĂ©rĂ©ment agnostiques de l’architecture et gardent l’erreur lĂ©gĂšre ; ces concepts sont simplement hors de leur pĂ©rimĂštre. +## Qu’est-ce qui change entre les approches ? -## 📊 En un coup d’Ɠil +| PrĂ©occupation | ErrorOr | FluentResults | FirstClassErrors | +| --- | --- | --- | --- | +| Abstraction principale | valeur ou erreurs | rĂ©sultat avec raisons | erreur structurĂ©e | +| Flux d’échec sous forme de valeur | central | central | disponible via `Outcome` | +| Erreurs ou raisons multiples | intĂ©grĂ© | intĂ©grĂ© | modĂ©lisĂ© via les erreurs internes ou une agrĂ©gation applicative | +| MĂ©tadonnĂ©es / faits propres Ă  l’occurrence | mĂ©tadonnĂ©es | mĂ©tadonnĂ©es | `ErrorContext` typĂ© | +| SĂ©paration dĂ©diĂ©e entre messages publics et internes | dĂ©finie par l’application | dĂ©finie par l’application | explicite dans le modĂšle central | +| Transport de la mĂȘme erreur sous forme d’exception typĂ©e | pas le modĂšle principal | pas le modĂšle principal | intĂ©grĂ© via `ToException()` | +| Taxonomie domaine / infrastructure / ports | dĂ©finie par l’application | dĂ©finie par l’application | intĂ©grĂ©e | +| Transience et direction de l’interaction | dĂ©finies par l’application | dĂ©finies par l’application | intĂ©grĂ©es pour les erreurs d’infrastructure | +| Documentation humaine gĂ©nĂ©rĂ©e | hors du pĂ©rimĂštre principal de la librairie | hors du pĂ©rimĂštre principal de la librairie | intĂ©grĂ©e | +| VĂ©rification de compatibilitĂ© du catalogue | hors du pĂ©rimĂštre principal de la librairie | hors du pĂ©rimĂštre principal de la librairie | intĂ©grĂ©e | -| | FirstClassErrors | ErrorOr | FluentResults | -|---|:---:|:---:|:---:| -| Retourner les erreurs comme valeurs (style railway) | ✅ (optionnel) | ✅ | ✅ | -| Lever la *mĂȘme* erreur comme exception typĂ©e | ✅ | ➖ | ➖ | -| ModĂšle d’erreur orientĂ© humain (titre, rĂšgle mĂ©tier, explication) | ✅ | ➖ | ➖ | -| Diagnostics : cause + origine + piste d’analyse | ✅ | ➖ | ➖ | -| Documentation gĂ©nĂ©rĂ©e depuis le code | ✅ | ➖ | ➖ | -| Taxonomie d’architecture (domaine / infrastructure / port) | ✅ | ➖ | ➖ | -| IdentitĂ© par occurrence (id + horodatage) | ✅ | ➖ | ➖ | -| Pipeline fluent | Optionnel, par conception | Central | Central | +« DĂ©fini par l’application » ou « hors du pĂ©rimĂštre principal » ne signifie pas impossible. Cela signifie que la prĂ©occupation n’est pas l’abstraction centrale de la librairie et qu’elle peut ĂȘtre prise en charge par des conventions applicatives ou un outillage externe. -*➖ signifie « pas un objectif de cette librairie », pas « mal fait » : ErrorOr et FluentResults sont concentrĂ©es sur le fait d’ĂȘtre des types rĂ©sultat Ă©purĂ©s.* +## Guide de dĂ©cision -## 🧭 Laquelle choisir ? +Choisissez **ErrorOr** lorsque : -- Prenez **ErrorOr** quand vous voulez un type rĂ©sultat minimal et ergonomique, avec une catĂ©gorisation d’erreurs propre et adaptĂ©e au HTTP. -- Prenez **FluentResults** quand vous voulez un rĂ©sultat portant des chaĂźnes de raisons riches et des mĂ©tadonnĂ©es. -- Prenez **FirstClassErrors** quand vous voulez que vos erreurs soient une **connaissance documentĂ©e et diagnosticable** — dĂ©crite une fois dans le code, transportĂ©e comme valeur ou levĂ©e comme exception, et transformĂ©e en catalogue sur lequel toute l’équipe peut s’appuyer. +- vous voulez principalement une union concise entre `T` et une ou plusieurs erreurs ; +- les erreurs de validation multiples sont courantes ; +- le matching et la composition fonctionnelle sont le style d’interaction principal ; +- une reprĂ©sentation lĂ©gĂšre de l’erreur suffit. -Elles ne se disputent pas vraiment le mĂȘme rĂŽle : les deux premiĂšres rendent les erreurs faciles Ă  *retourner* ; FirstClassErrors les rend faciles Ă  *comprendre, supporter et documenter*. +Choisissez **FluentResults** lorsque : + +- vous souhaitez reprĂ©senter des raisons de succĂšs comme d’échec ; +- les chaĂźnes de raisons imbriquĂ©es et les mĂ©tadonnĂ©es sont centrales ; +- le graphe de rĂ©sultat est lui-mĂȘme le modĂšle que vous voulez enrichir et composer. + +Choisissez **FirstClassErrors** lorsque : + +- les erreurs sont des concepts durables utilisĂ©s par les dĂ©veloppeurs, le support, l’exploitation ou les clients ; +- les messages publics et de diagnostic doivent avoir des audiences explicites ; +- une mĂȘme erreur doit circuler comme donnĂ©e, outcome ou exception ; +- les Ă©checs mĂ©tier et infrastructurels doivent porter un sens opĂ©rationnel diffĂ©rent ; +- la documentation gĂ©nĂ©rĂ©e et les contrĂŽles de compatibilitĂ© font partie du besoin. + +## Une combinaison peut aussi ĂȘtre valable + +Ces choix ne sont pas toujours exclusifs. Une application peut utiliser une librairie de rĂ©sultat gĂ©nĂ©raliste Ă  certaines frontiĂšres tout en conservant un catalogue d’erreurs documentĂ© sĂ©parĂ©. + +Avant de combiner les modĂšles, dĂ©cidez quel type possĂšde l’identitĂ© stable de l’erreur. Dupliquer les codes, les messages, les mĂ©tadonnĂ©es et les mappings entre deux modĂšles concurrents crĂ©e gĂ©nĂ©ralement plus de travail que cela n’en Ă©conomise. + +## Questions Ă  poser avant de choisir + +1. Le problĂšme principal est-il le **contrĂŽle du flux**, la **composition des raisons** ou la **connaissance partagĂ©e des erreurs** ? +2. Une mĂȘme dĂ©finition d’erreur doit-elle supporter le retour et l’exception ? +3. Qui consomme le modĂšle : seulement le code, ou Ă©galement le support et l’exploitation ? +4. Les codes et les clĂ©s de contexte sont-ils considĂ©rĂ©s comme un contrat versionnĂ© ? +5. La documentation gĂ©nĂ©rĂ©e est-elle une exigence ou une prĂ©occupation externe ? +6. L’application a-t-elle besoin d’une sĂ©mantique intĂ©grĂ©e pour le domaine et l’infrastructure ? +7. Combien de conventions ĂȘtes-vous prĂȘt Ă  construire autour d’un type rĂ©sultat plus petit ? + +Le meilleur choix est le plus petit modĂšle qui couvre les besoins rĂ©els sans obliger l’application Ă  reconstruire ailleurs les sĂ©mantiques manquantes. + +--- + + + +--- \ No newline at end of file From 5539df46341a636c0cad842f80a8818294ffc039 Mon Sep 17 00:00:00 2001 From: Sylvain Aurat Date: Tue, 14 Jul 2026 17:34:19 +0200 Subject: [PATCH 03/10] docs: add reader-oriented documentation map --- doc/DocumentationMap.en.md | 106 +++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 doc/DocumentationMap.en.md diff --git a/doc/DocumentationMap.en.md b/doc/DocumentationMap.en.md new file mode 100644 index 0000000..2ce7293 --- /dev/null +++ b/doc/DocumentationMap.en.md @@ -0,0 +1,106 @@ +# Documentation map + +🌍 **Languages:** +🇬🇧 English (this file) | đŸ‡«đŸ‡· [Français](./DocumentationMap.fr.md) + +FirstClassErrors documentation is organized by **reader intent**, not by implementation namespace. + +Start with the question you are trying to answer. Each primary page may link to more focused guides or references for advanced details. + +## I am discovering the library + +Follow this path when you are deciding whether FirstClassErrors fits your application. + +1. [Getting Started](GettingStarted.en.md) — install the library, create an error, and generate a first catalog. +2. [Design Principles](DesignPrinciples.en.md) — understand why the error is the model and transport is a separate choice. +3. [When Not to Use FirstClassErrors](WhenNotToUseFirstClassErrors.en.md) — identify cases where the library would add more ceremony than value. +4. [Comparison with error-handling libraries](ComparisonWithOtherLibraries.en.md) — compare FirstClassErrors with ErrorOr and FluentResults through one concrete scenario. + +## I need to understand the model + +Use these pages before defining project-wide conventions. + +- [Core Concepts](CoreConcepts.en.md) — `Error`, factories, documentation, exceptions, and `Outcome`. +- [Error Context Guide](ErrorContext.en.md) — structured facts attached to one occurrence. +- [Usage Patterns](UsagePatterns.en.md) — choose between exceptions, outcomes, domain errors, and infrastructure errors. + +The primary pages link to any dedicated taxonomy or composition guides available in the current documentation version. + +## I am writing an error + +Use this path when adding or reviewing an application error. + +1. [Writing Errors Guide](WritingErrorsGuide.en.md) — code, title, description, rule, diagnostics, and examples. +2. [Best Practices](BestPractices.en.md) — project and pull-request review checklist. +3. [Internationalization](Internationalization.en.md) — localize public and documentation content while keeping stable identifiers invariant. +4. [Analyzer rules](analyzers/README.md) — understand the compile-time checks that protect the model and documentation links. + +## I am using errors in application code + +- [Usage Patterns](UsagePatterns.en.md) — select the right representation for common situations. +- [Error Context Guide](ErrorContext.en.md) — attach useful, safe occurrence-level facts. +- [Testing Guide](Testing.en.md) — assert outcomes and errors without manual plumbing. +- [FAQ](FAQ.en.md) — resolve common design questions and find the relevant focused guide. + +## I am integrating delivery and operations + +1. [CI/CD and Operational Integration](OperationalIntegration.en.md) — generate and publish the catalog as part of delivery. +2. [Catalog Versioning — overview and workflow](CatalogVersioning.en.md) — understand snapshots, baselines, and compatibility. +3. [Catalog Versioning — command reference](CatalogVersioningReference.en.md) — find exact CLI options and exit codes. +4. [Catalog Versioning — CI/CD integration](CatalogVersioningCI.en.md) — implement read-only contract checks in pipelines. + +The operational integration pages link to any dedicated logging guidance available in the current documentation version. + +## I am extending the documentation pipeline + +- [Architecture of the Documentation Pipeline](ArchitectureOfTheDocumentationPipeline.en.md) — understand the end-to-end model and component responsibilities. +- [Writing a custom renderer](WritingACustomRenderer.en.md) — implement and register another output format. +- [Internationalization](Internationalization.en.md) — understand the extraction/rendering culture boundary. + +The architecture page links to any focused extraction and project-discovery reference available in the current documentation version. + +## I need a reference, not a tutorial + +Use these pages when you already understand the model and need exact behavior. + +- [Catalog Versioning command reference](CatalogVersioningReference.en.md) +- [Analyzer rules](analyzers/README.md) +- [FAQ](FAQ.en.md) + +Architecture, renderer, testing, and operational pages may also link to focused reference pages introduced by newer documentation versions. + +## Suggested team reading order + +For a team adopting FirstClassErrors, a practical sequence is: + +1. Getting Started; +2. Design Principles; +3. Core Concepts; +4. Writing Errors Guide; +5. Usage Patterns; +6. Testing Guide; +7. CI/CD and Operational Integration; +8. Catalog Versioning. + +After that shared foundation, specialists can read the architecture, renderer, internationalization, logging, analyzer, and command-reference material relevant to their work. + +## Keep one source of truth + +Avoid copying large explanations between project guidelines and this documentation. + +Project-specific rules should state the local decision and link to the relevant guide. For example: + +```text +Application errors must be created through named factories. +See Writing Errors Guide and Best Practices. +``` + +This keeps local conventions short while allowing the library documentation to evolve without creating several conflicting explanations. + +--- + + + +--- \ No newline at end of file From 33bfb8272f205fc8f2ddc333b45bed9ee1c18946 Mon Sep 17 00:00:00 2001 From: Sylvain Aurat Date: Tue, 14 Jul 2026 17:35:17 +0200 Subject: [PATCH 04/10] docs: add reader-oriented documentation map --- doc/DocumentationMap.fr.md | 106 +++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 doc/DocumentationMap.fr.md diff --git a/doc/DocumentationMap.fr.md b/doc/DocumentationMap.fr.md new file mode 100644 index 0000000..c9c1d16 --- /dev/null +++ b/doc/DocumentationMap.fr.md @@ -0,0 +1,106 @@ +# Carte de la documentation + +🌍 **Langues :** +🇬🇧 [English](./DocumentationMap.en.md) | đŸ‡«đŸ‡· Français (ce fichier) + +La documentation de FirstClassErrors est organisĂ©e selon **l’intention du lecteur**, et non selon les namespaces d’implĂ©mentation. + +Partez de la question Ă  laquelle vous cherchez Ă  rĂ©pondre. Chaque page principale peut ensuite renvoyer vers des guides ou des rĂ©fĂ©rences plus spĂ©cialisĂ©s. + +## Je dĂ©couvre la librairie + +Suivez ce parcours pour dĂ©terminer si FirstClassErrors correspond Ă  votre application. + +1. [Premiers pas](GettingStarted.fr.md) — installer la librairie, crĂ©er une erreur et gĂ©nĂ©rer un premier catalogue. +2. [Principes de conception](DesignPrinciples.fr.md) — comprendre pourquoi l’erreur est le modĂšle et pourquoi le transport est un choix sĂ©parĂ©. +3. [Quand ne pas utiliser FirstClassErrors](WhenNotToUseFirstClassErrors.fr.md) — reconnaĂźtre les situations oĂč la librairie apporterait plus de formalisme que de valeur. +4. [Comparaison avec les librairies de gestion d’erreurs](ComparisonWithOtherLibraries.fr.md) — comparer FirstClassErrors, ErrorOr et FluentResults Ă  partir d’un mĂȘme scĂ©nario concret. + +## Je dois comprendre le modĂšle + +Lisez ces pages avant de dĂ©finir des conventions Ă  l’échelle d’un projet. + +- [Concepts fondamentaux](CoreConcepts.fr.md) — `Error`, factories, documentation, exceptions et `Outcome`. +- [Guide du contexte d’erreur](ErrorContext.fr.md) — faits structurĂ©s propres Ă  une occurrence. +- [Cas d’usage](UsagePatterns.fr.md) — choisir entre exceptions, outcomes, erreurs de domaine et erreurs d’infrastructure. + +Les pages principales renvoient vers les Ă©ventuels guides dĂ©diĂ©s Ă  la taxonomie ou Ă  la composition disponibles dans la version courante de la documentation. + +## J’écris une erreur + +Utilisez ce parcours lors de l’ajout ou de la revue d’une erreur applicative. + +1. [Guide d’écriture des erreurs](WritingErrorsGuide.fr.md) — code, titre, description, rĂšgle, diagnostics et exemples. +2. [Bonnes pratiques](BestPractices.fr.md) — checklist de projet et de pull request. +3. [Internationalisation](Internationalisation.fr.md) — localiser le contenu public et documentaire tout en gardant les identifiants stables invariants. +4. [RĂšgles d’analyse](analyzers/README.fr.md) — comprendre les contrĂŽles de compilation qui protĂšgent le modĂšle et les liens documentaires. + +## J’utilise les erreurs dans le code applicatif + +- [Cas d’usage](UsagePatterns.fr.md) — choisir la bonne reprĂ©sentation selon la situation. +- [Guide du contexte d’erreur](ErrorContext.fr.md) — attacher des faits utiles, sĂ»rs et propres Ă  l’occurrence. +- [Guide des tests](Testing.fr.md) — vĂ©rifier les outcomes et les erreurs sans plomberie manuelle. +- [FAQ](FAQ.fr.md) — rĂ©soudre les questions de conception courantes et trouver le guide spĂ©cialisĂ© pertinent. + +## J’intĂšgre la livraison et l’exploitation + +1. [IntĂ©gration CI/CD et exploitation](OperationalIntegration.fr.md) — gĂ©nĂ©rer et publier le catalogue dans la chaĂźne de livraison. +2. [Versionnage du catalogue — vue d’ensemble et workflow](CatalogVersioning.fr.md) — comprendre snapshots, baseline et compatibilitĂ©. +3. [Versionnage du catalogue — rĂ©fĂ©rence des commandes](CatalogVersioningReference.fr.md) — retrouver les options exactes de la CLI et les codes de sortie. +4. [Versionnage du catalogue — intĂ©gration CI/CD](CatalogVersioningCI.fr.md) — mettre en place des contrĂŽles de contrat en lecture seule dans les pipelines. + +Les pages d’intĂ©gration opĂ©rationnelle renvoient vers les Ă©ventuels guides dĂ©diĂ©s au logging disponibles dans la version courante de la documentation. + +## J’étends le pipeline documentaire + +- [Architecture du pipeline de documentation](ArchitectureOfTheDocumentationPipeline.fr.md) — comprendre le modĂšle de bout en bout et la responsabilitĂ© de chaque composant. +- [Écrire son propre renderer](WritingACustomRenderer.fr.md) — implĂ©menter et enregistrer un nouveau format de sortie. +- [Internationalisation](Internationalisation.fr.md) — comprendre la frontiĂšre de culture entre extraction et rendu. + +La page d’architecture renvoie vers l’éventuelle rĂ©fĂ©rence dĂ©diĂ©e Ă  l’extraction et Ă  la dĂ©couverte des projets disponible dans la version courante de la documentation. + +## J’ai besoin d’une rĂ©fĂ©rence, pas d’un tutoriel + +Utilisez ces pages lorsque vous connaissez dĂ©jĂ  le modĂšle et recherchez un comportement exact. + +- [RĂ©fĂ©rence des commandes de versionnage](CatalogVersioningReference.fr.md) +- [RĂšgles d’analyse](analyzers/README.fr.md) +- [FAQ](FAQ.fr.md) + +Les pages d’architecture, de renderer, de tests et d’exploitation peuvent Ă©galement renvoyer vers des rĂ©fĂ©rences spĂ©cialisĂ©es introduites dans les versions plus rĂ©centes de la documentation. + +## Ordre de lecture conseillĂ© pour une Ă©quipe + +Pour une Ă©quipe qui adopte FirstClassErrors, un ordre pratique est : + +1. Premiers pas ; +2. Principes de conception ; +3. Concepts fondamentaux ; +4. Guide d’écriture des erreurs ; +5. Cas d’usage ; +6. Guide des tests ; +7. IntĂ©gration CI/CD et exploitation ; +8. Versionnage du catalogue. + +AprĂšs ce socle commun, les spĂ©cialistes peuvent lire les contenus d’architecture, de renderer, d’internationalisation, de logging, d’analyseurs et de rĂ©fĂ©rence CLI utiles Ă  leur travail. + +## Garder une seule source de vĂ©ritĂ© + +Évitez de recopier de longues explications entre les conventions du projet et cette documentation. + +Les rĂšgles propres au projet devraient exprimer la dĂ©cision locale et renvoyer vers le guide correspondant. Par exemple : + +```text +Les erreurs applicatives doivent ĂȘtre crĂ©Ă©es via des factories nommĂ©es. +Voir le Guide d’écriture des erreurs et les Bonnes pratiques. +``` + +Les conventions locales restent ainsi courtes, tandis que la documentation de la librairie peut Ă©voluer sans crĂ©er plusieurs explications contradictoires. + +--- + + + +--- \ No newline at end of file From 16b3e7e9c25a9dca870ef38fe940745b737f9415 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 15 Jul 2026 07:04:28 +0000 Subject: [PATCH 05/10] docs: gloss library terms for first-contact evaluators The comparison page and the documentation map are entry points read by people who do not know FirstClassErrors yet. Gloss the library-specific vocabulary they lean on, in both languages: - introduce Outcome as the success-or-failure result type in the comparison's topic sentence; - gloss transience, interaction direction, and port in the comparison table rows so they can be evaluated without the taxonomy page; - mark Code.PaymentDeclined and ContextKey.PaymentId as application-defined constants and show the literal stable code, matching what the ErrorOr sample exposes; - say what the generated catalog is at its mention; - clarify transport and catalog in the map's discovery entries, and drop the hedge sentence about focused reference pages in newer documentation versions. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LUaMS5EHzAdQHBJzrYvKTj --- doc/ComparisonWithOtherLibraries.en.md | 10 ++++++---- doc/ComparisonWithOtherLibraries.fr.md | 10 ++++++---- doc/DocumentationMap.en.md | 6 ++---- doc/DocumentationMap.fr.md | 6 ++---- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/ComparisonWithOtherLibraries.en.md b/doc/ComparisonWithOtherLibraries.en.md index f2f5812..ad2f992 100644 --- a/doc/ComparisonWithOtherLibraries.en.md +++ b/doc/ComparisonWithOtherLibraries.en.md @@ -67,13 +67,15 @@ Choose this style when the result and its reason graph are the primary abstracti ## FirstClassErrors: an error model with several transports -FirstClassErrors centres the API on the error itself. `Outcome` is one transport, and `ToException()` is another. +FirstClassErrors centres the API on the error itself. `Outcome` (the library's success-or-failure result type) is one way the error travels; `ToException()` is another. ```csharp internal static DomainError PaymentDeclined( string providerCode, Guid paymentId) { + // Code.PaymentDeclined and ContextKey.PaymentId are application-defined + // constants: ErrorCode.Create("PAYMENT_DECLINED") and a typed context key. return DomainError.Create( Code.PaymentDeclined, diagnosticMessage: @@ -108,7 +110,7 @@ throw PaymentError .ToException(); ``` -The error can additionally be linked to structured documentation describing its title, rule, possible causes, analysis leads, and examples. The generated catalog and catalog-versioning workflow are part of the library's intended use. +The error can additionally be linked to structured documentation describing its title, rule, possible causes, analysis leads, and examples. The generated catalog (a human-readable reference of every documented error) and the versioning workflow that guards it against breaking changes are part of the library's intended use. Choose this style when the error definition itself must remain stable, documented, diagnosable, and independent from whether a caller returns or throws it. @@ -122,8 +124,8 @@ Choose this style when the error definition itself must remain stable, documente | Metadata / occurrence facts | metadata | metadata | typed `ErrorContext` | | Dedicated public vs internal messages | application-defined | application-defined | explicit in the core model | | Typed exception transport from the same error | not the primary model | not the primary model | built in through `ToException()` | -| Domain / infrastructure / port taxonomy | application-defined | application-defined | built in | -| Transience and interaction direction | application-defined | application-defined | built in for infrastructure errors | +| Domain / infrastructure / port (incoming/outgoing boundary) taxonomy | application-defined | application-defined | built in | +| Transience (is retrying meaningful?) and interaction direction (incoming vs outgoing) | application-defined | application-defined | built in for infrastructure errors | | Generated human documentation | outside the library's main scope | outside the library's main scope | built in | | Catalog compatibility checks | outside the library's main scope | outside the library's main scope | built in | diff --git a/doc/ComparisonWithOtherLibraries.fr.md b/doc/ComparisonWithOtherLibraries.fr.md index b816c50..a79e260 100644 --- a/doc/ComparisonWithOtherLibraries.fr.md +++ b/doc/ComparisonWithOtherLibraries.fr.md @@ -67,13 +67,15 @@ Choisissez cette approche lorsque le rĂ©sultat et son graphe de raisons sont l ## FirstClassErrors : un modĂšle d’erreur avec plusieurs transports -FirstClassErrors place l’erreur elle-mĂȘme au centre. `Outcome` est un transport possible ; `ToException()` en est un autre. +FirstClassErrors place l’erreur elle-mĂȘme au centre. `Outcome` (le type rĂ©sultat succĂšs-ou-Ă©chec de la bibliothĂšque) est une façon de faire voyager l’erreur ; `ToException()` en est une autre. ```csharp internal static DomainError PaymentDeclined( string providerCode, Guid paymentId) { + // Code.PaymentDeclined et ContextKey.PaymentId sont des constantes dĂ©finies + // par l'application : ErrorCode.Create("PAYMENT_DECLINED") et une clĂ© de contexte typĂ©e. return DomainError.Create( Code.PaymentDeclined, diagnosticMessage: @@ -108,7 +110,7 @@ throw PaymentError .ToException(); ``` -L’erreur peut en outre ĂȘtre liĂ©e Ă  une documentation structurĂ©e dĂ©crivant son titre, sa rĂšgle, ses causes possibles, ses pistes d’analyse et ses exemples. Le catalogue gĂ©nĂ©rĂ© et son workflow de versionnage font partie de l’usage prĂ©vu de la librairie. +L’erreur peut en outre ĂȘtre liĂ©e Ă  une documentation structurĂ©e dĂ©crivant son titre, sa rĂšgle, ses causes possibles, ses pistes d’analyse et ses exemples. Le catalogue gĂ©nĂ©rĂ© (une rĂ©fĂ©rence lisible de toutes les erreurs documentĂ©es) et le workflow de versionnage qui le protĂšge des changements cassants font partie de l’usage prĂ©vu de la librairie. Choisissez cette approche lorsque la dĂ©finition de l’erreur doit rester stable, documentĂ©e, diagnosticable et indĂ©pendante du fait qu’un appelant la retourne ou la lĂšve. @@ -122,8 +124,8 @@ Choisissez cette approche lorsque la dĂ©finition de l’erreur doit rester stabl | MĂ©tadonnĂ©es / faits propres Ă  l’occurrence | mĂ©tadonnĂ©es | mĂ©tadonnĂ©es | `ErrorContext` typĂ© | | SĂ©paration dĂ©diĂ©e entre messages publics et internes | dĂ©finie par l’application | dĂ©finie par l’application | explicite dans le modĂšle central | | Transport de la mĂȘme erreur sous forme d’exception typĂ©e | pas le modĂšle principal | pas le modĂšle principal | intĂ©grĂ© via `ToException()` | -| Taxonomie domaine / infrastructure / ports | dĂ©finie par l’application | dĂ©finie par l’application | intĂ©grĂ©e | -| Transience et direction de l’interaction | dĂ©finies par l’application | dĂ©finies par l’application | intĂ©grĂ©es pour les erreurs d’infrastructure | +| Taxonomie domaine / infrastructure / ports (frontiĂšres entrantes/sortantes) | dĂ©finie par l’application | dĂ©finie par l’application | intĂ©grĂ©e | +| Transience (retenter peut-il rĂ©ussir ?) et direction de l’interaction (entrante ou sortante) | dĂ©finies par l’application | dĂ©finies par l’application | intĂ©grĂ©es pour les erreurs d’infrastructure | | Documentation humaine gĂ©nĂ©rĂ©e | hors du pĂ©rimĂštre principal de la librairie | hors du pĂ©rimĂštre principal de la librairie | intĂ©grĂ©e | | VĂ©rification de compatibilitĂ© du catalogue | hors du pĂ©rimĂštre principal de la librairie | hors du pĂ©rimĂštre principal de la librairie | intĂ©grĂ©e | diff --git a/doc/DocumentationMap.en.md b/doc/DocumentationMap.en.md index 2ce7293..3fe80e2 100644 --- a/doc/DocumentationMap.en.md +++ b/doc/DocumentationMap.en.md @@ -11,8 +11,8 @@ Start with the question you are trying to answer. Each primary page may link to Follow this path when you are deciding whether FirstClassErrors fits your application. -1. [Getting Started](GettingStarted.en.md) — install the library, create an error, and generate a first catalog. -2. [Design Principles](DesignPrinciples.en.md) — understand why the error is the model and transport is a separate choice. +1. [Getting Started](GettingStarted.en.md) — install the library, create an error, and generate a first human-readable error catalog. +2. [Design Principles](DesignPrinciples.en.md) — understand why the error is the model and how it travels (exception or return value) is a separate choice. 3. [When Not to Use FirstClassErrors](WhenNotToUseFirstClassErrors.en.md) — identify cases where the library would add more ceremony than value. 4. [Comparison with error-handling libraries](ComparisonWithOtherLibraries.en.md) — compare FirstClassErrors with ErrorOr and FluentResults through one concrete scenario. @@ -67,8 +67,6 @@ Use these pages when you already understand the model and need exact behavior. - [Analyzer rules](analyzers/README.md) - [FAQ](FAQ.en.md) -Architecture, renderer, testing, and operational pages may also link to focused reference pages introduced by newer documentation versions. - ## Suggested team reading order For a team adopting FirstClassErrors, a practical sequence is: diff --git a/doc/DocumentationMap.fr.md b/doc/DocumentationMap.fr.md index c9c1d16..dbeea9b 100644 --- a/doc/DocumentationMap.fr.md +++ b/doc/DocumentationMap.fr.md @@ -11,8 +11,8 @@ Partez de la question Ă  laquelle vous cherchez Ă  rĂ©pondre. Chaque page princi Suivez ce parcours pour dĂ©terminer si FirstClassErrors correspond Ă  votre application. -1. [Premiers pas](GettingStarted.fr.md) — installer la librairie, crĂ©er une erreur et gĂ©nĂ©rer un premier catalogue. -2. [Principes de conception](DesignPrinciples.fr.md) — comprendre pourquoi l’erreur est le modĂšle et pourquoi le transport est un choix sĂ©parĂ©. +1. [Premiers pas](GettingStarted.fr.md) — installer la librairie, crĂ©er une erreur et gĂ©nĂ©rer un premier catalogue d’erreurs lisible par des humains. +2. [Principes de conception](DesignPrinciples.fr.md) — comprendre pourquoi l’erreur est le modĂšle et pourquoi sa façon de voyager (exception ou valeur de retour) est un choix sĂ©parĂ©. 3. [Quand ne pas utiliser FirstClassErrors](WhenNotToUseFirstClassErrors.fr.md) — reconnaĂźtre les situations oĂč la librairie apporterait plus de formalisme que de valeur. 4. [Comparaison avec les librairies de gestion d’erreurs](ComparisonWithOtherLibraries.fr.md) — comparer FirstClassErrors, ErrorOr et FluentResults Ă  partir d’un mĂȘme scĂ©nario concret. @@ -67,8 +67,6 @@ Utilisez ces pages lorsque vous connaissez dĂ©jĂ  le modĂšle et recherchez un co - [RĂšgles d’analyse](analyzers/README.fr.md) - [FAQ](FAQ.fr.md) -Les pages d’architecture, de renderer, de tests et d’exploitation peuvent Ă©galement renvoyer vers des rĂ©fĂ©rences spĂ©cialisĂ©es introduites dans les versions plus rĂ©centes de la documentation. - ## Ordre de lecture conseillĂ© pour une Ă©quipe Pour une Ă©quipe qui adopte FirstClassErrors, un ordre pratique est : From b90e4b9a2dd7d87e018b4eaf7066f82efd9c3f69 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 15 Jul 2026 22:59:41 +0000 Subject: [PATCH 06/10] docs: make the library comparison fairer and more symmetric MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address review feedback on the neutrality of the comparison page: - State up front that the scenario emphasizes error stability, diagnosis, and documentation (FirstClassErrors' core), and that other scenarios — heavy multi-error validation or intensive functional composition — can favor ErrorOr or FluentResults. - Give FirstClassErrors a minimal Outcome example of comparable length to the ErrorOr and FluentResults ones, then move the factory, exception, and catalog/versioning material into a dedicated "What FirstClassErrors adds to the result model" section, so the first read is symmetric. - Sharpen wording: name ErrorOr's HTTP mapping concretely instead of a bare mention; describe FluentResults' reasons model in terms of its real capabilities; in the table, say multiple-error aggregation is left to the application, and that ToException() yields a structured, category-typed exception (verified: DomainException et al. carry .Error). --- doc/ComparisonWithOtherLibraries.en.md | 50 +++++++++++++++----------- doc/ComparisonWithOtherLibraries.fr.md | 50 +++++++++++++++----------- 2 files changed, 58 insertions(+), 42 deletions(-) diff --git a/doc/ComparisonWithOtherLibraries.en.md b/doc/ComparisonWithOtherLibraries.en.md index ad2f992..5217d9d 100644 --- a/doc/ComparisonWithOtherLibraries.en.md +++ b/doc/ComparisonWithOtherLibraries.en.md @@ -7,7 +7,7 @@ ErrorOr, FluentResults, and FirstClassErrors all help applications represent failure explicitly, but they optimize for different primary goals. -This page does not rank them. It shows the same situation through three different centres of gravity so you can choose the model that best matches your system. +This page does not try to rank them in general. The scenario below deliberately emphasizes error stability, diagnosis, and documentation — the primary focus of FirstClassErrors — so it plays to its strengths; other scenarios, such as heavy multi-error validation or intensive functional composition, can naturally favor ErrorOr or FluentResults. Within this scenario, it shows the same situation through three different centres of gravity so you can choose the model that best matches your system. ## The scenario @@ -41,7 +41,7 @@ public ErrorOr Pay(Order order) A caller can inspect, match, switch on, or compose the result. Built-in error types and metadata support categorization and application-specific information. -Choose this style when the central need is an ergonomic value-or-errors flow, especially when multiple validation errors or HTTP-oriented result handling are important. +Choose this style when the central need is an ergonomic value-or-errors flow, especially when multiple validation errors are common, or when error types are mapped to HTTP responses. ## FluentResults: a result with reasons and metadata @@ -61,13 +61,34 @@ public Result Pay(Order order) } ``` -The reasons model is useful when an application needs rich success and failure chains, metadata, and configurable result handling. +The reasons model is useful when an application wants to enrich both successes and failures, keep hierarchical causes, and compose several results. Choose this style when the result and its reason graph are the primary abstraction you want to compose. ## FirstClassErrors: an error model with several transports -FirstClassErrors centres the API on the error itself. `Outcome` (the library's success-or-failure result type) is one way the error travels; `ToException()` is another. +FirstClassErrors centres the API on the error itself. A named factory creates the error; `Outcome` (the library's success-or-failure result type) is one way it travels: + +```csharp +public Outcome Pay(Order order) +{ + if (provider.Declines(order, out string providerCode)) + { + return Outcome.Failure( + PaymentError.PaymentDeclined(providerCode, order.PaymentId)); + } + + return Outcome.Success(new Receipt(order.Id)); +} +``` + +At this level the three libraries look alike: a method returns a success or a failure the caller inspects. The difference is where the failure's meaning lives — [what FirstClassErrors adds](#what-firstclasserrors-adds-to-the-result-model) is shown below. + +Choose this style when the error definition itself must remain stable, documented, diagnosable, and independent from whether a caller returns or throws it. + +## What FirstClassErrors adds to the result model + +The transport above looks like the other two. The difference is that the error is defined once, in a named factory that carries its code, messages, occurrence context, and a link to documentation: ```csharp internal static DomainError PaymentDeclined( @@ -89,20 +110,7 @@ internal static DomainError PaymentDeclined( } ``` -```csharp -public Outcome Pay(Order order) -{ - if (provider.Declines(order, out string providerCode)) - { - return Outcome.Failure( - PaymentError.PaymentDeclined(providerCode, order.PaymentId)); - } - - return Outcome.Success(new Receipt(order.Id)); -} -``` - -The same factory can also feed exception flow: +The same factory feeds exception flow. The error travels as a structured, category-typed exception (`DomainException` here) carrying the same `Error`: ```csharp throw PaymentError @@ -112,7 +120,7 @@ throw PaymentError The error can additionally be linked to structured documentation describing its title, rule, possible causes, analysis leads, and examples. The generated catalog (a human-readable reference of every documented error) and the versioning workflow that guards it against breaking changes are part of the library's intended use. -Choose this style when the error definition itself must remain stable, documented, diagnosable, and independent from whether a caller returns or throws it. +None of this changes the `Pay` method above: the transport stays small, and the durable error knowledge lives beside the error, not in each call site. ## What changes between the approaches? @@ -120,10 +128,10 @@ Choose this style when the error definition itself must remain stable, documente | --- | --- | --- | --- | | Primary abstraction | value or errors | result with reasons | structured error | | Value-based failure flow | central | central | available through `Outcome` | -| Multiple errors or reasons | built in | built in | modeled through inner errors or application aggregation | +| Multiple errors or reasons | built in | built in | structured causes; aggregating independent errors is left to the application | | Metadata / occurrence facts | metadata | metadata | typed `ErrorContext` | | Dedicated public vs internal messages | application-defined | application-defined | explicit in the core model | -| Typed exception transport from the same error | not the primary model | not the primary model | built in through `ToException()` | +| Exception transport from the same error definition | not the primary model | not the primary model | built in via `ToException()` — a structured, category-typed exception | | Domain / infrastructure / port (incoming/outgoing boundary) taxonomy | application-defined | application-defined | built in | | Transience (is retrying meaningful?) and interaction direction (incoming vs outgoing) | application-defined | application-defined | built in for infrastructure errors | | Generated human documentation | outside the library's main scope | outside the library's main scope | built in | diff --git a/doc/ComparisonWithOtherLibraries.fr.md b/doc/ComparisonWithOtherLibraries.fr.md index a79e260..d262cff 100644 --- a/doc/ComparisonWithOtherLibraries.fr.md +++ b/doc/ComparisonWithOtherLibraries.fr.md @@ -7,7 +7,7 @@ ErrorOr, FluentResults et FirstClassErrors permettent toutes de reprĂ©senter explicitement un Ă©chec, mais elles optimisent des besoins principaux diffĂ©rents. -Cette page ne les classe pas. Elle montre une mĂȘme situation Ă  travers trois centres de gravitĂ© afin de choisir le modĂšle qui correspond rĂ©ellement au systĂšme. +Cette page ne cherche pas Ă  Ă©tablir un classement gĂ©nĂ©ral. Le scĂ©nario ci-dessous met volontairement l’accent sur la stabilitĂ©, le diagnostic et la documentation des erreurs — le pĂ©rimĂštre principal de FirstClassErrors — et joue donc en sa faveur ; d’autres scĂ©narios, comme la validation multiple intensive ou la composition fonctionnelle poussĂ©e, peuvent naturellement favoriser ErrorOr ou FluentResults. Dans ce scĂ©nario, elle montre une mĂȘme situation Ă  travers trois centres de gravitĂ© afin de choisir le modĂšle qui correspond rĂ©ellement au systĂšme. ## Le scĂ©nario @@ -41,7 +41,7 @@ public ErrorOr Pay(Order order) L’appelant peut inspecter, faire un `Match`, un `Switch` ou composer le rĂ©sultat. Les types d’erreurs intĂ©grĂ©s et les mĂ©tadonnĂ©es permettent de catĂ©goriser l’échec et d’ajouter des informations propres Ă  l’application. -Choisissez cette approche lorsque le besoin central est un flux ergonomique « valeur ou erreurs », notamment lorsque plusieurs erreurs de validation ou une intĂ©gration HTTP orientĂ©e rĂ©sultat sont importantes. +Choisissez cette approche lorsque le besoin central est un flux ergonomique « valeur ou erreurs », notamment lorsque plusieurs erreurs de validation sont courantes, ou lorsque les types d’erreurs sont mappĂ©s vers des rĂ©ponses HTTP. ## FluentResults : un rĂ©sultat portant des raisons et des mĂ©tadonnĂ©es @@ -61,13 +61,34 @@ public Result Pay(Order order) } ``` -Le modĂšle de raisons est utile lorsqu’une application a besoin de chaĂźnes riches de succĂšs et d’échecs, de mĂ©tadonnĂ©es et d’une gestion configurable des rĂ©sultats. +Le modĂšle de raisons est utile lorsqu’une application souhaite enrichir aussi bien les succĂšs que les Ă©checs, conserver des causes hiĂ©rarchiques et composer plusieurs rĂ©sultats. Choisissez cette approche lorsque le rĂ©sultat et son graphe de raisons sont l’abstraction principale que vous souhaitez enrichir et composer. ## FirstClassErrors : un modĂšle d’erreur avec plusieurs transports -FirstClassErrors place l’erreur elle-mĂȘme au centre. `Outcome` (le type rĂ©sultat succĂšs-ou-Ă©chec de la bibliothĂšque) est une façon de faire voyager l’erreur ; `ToException()` en est une autre. +FirstClassErrors place l’erreur elle-mĂȘme au centre. Une factory nommĂ©e crĂ©e l’erreur ; `Outcome` (le type rĂ©sultat succĂšs-ou-Ă©chec de la bibliothĂšque) est une façon de la faire voyager : + +```csharp +public Outcome Pay(Order order) +{ + if (provider.Declines(order, out string providerCode)) + { + return Outcome.Failure( + PaymentError.PaymentDeclined(providerCode, order.PaymentId)); + } + + return Outcome.Success(new Receipt(order.Id)); +} +``` + +À ce niveau, les trois bibliothĂšques se ressemblent : une mĂ©thode retourne un succĂšs ou un Ă©chec que l’appelant inspecte. La diffĂ©rence tient Ă  l’endroit oĂč vit le sens de l’échec — [ce que FirstClassErrors ajoute](#ce-que-firstclasserrors-ajoute-au-modĂšle-de-rĂ©sultat) est montrĂ© plus bas. + +Choisissez cette approche lorsque la dĂ©finition de l’erreur doit rester stable, documentĂ©e, diagnosticable et indĂ©pendante du fait qu’un appelant la retourne ou la lĂšve. + +## Ce que FirstClassErrors ajoute au modĂšle de rĂ©sultat + +Le transport ci-dessus ressemble aux deux autres. La diffĂ©rence, c’est que l’erreur est dĂ©finie une seule fois, dans une factory nommĂ©e qui porte son code, ses messages, son contexte d’occurrence et un lien vers sa documentation : ```csharp internal static DomainError PaymentDeclined( @@ -89,20 +110,7 @@ internal static DomainError PaymentDeclined( } ``` -```csharp -public Outcome Pay(Order order) -{ - if (provider.Declines(order, out string providerCode)) - { - return Outcome.Failure( - PaymentError.PaymentDeclined(providerCode, order.PaymentId)); - } - - return Outcome.Success(new Receipt(order.Id)); -} -``` - -La mĂȘme factory peut aussi alimenter un flux par exception : +La mĂȘme factory alimente le flux par exception. L’erreur voyage alors comme une exception structurĂ©e et typĂ©e par catĂ©gorie (`DomainException` ici) portant la mĂȘme `Error` : ```csharp throw PaymentError @@ -112,7 +120,7 @@ throw PaymentError L’erreur peut en outre ĂȘtre liĂ©e Ă  une documentation structurĂ©e dĂ©crivant son titre, sa rĂšgle, ses causes possibles, ses pistes d’analyse et ses exemples. Le catalogue gĂ©nĂ©rĂ© (une rĂ©fĂ©rence lisible de toutes les erreurs documentĂ©es) et le workflow de versionnage qui le protĂšge des changements cassants font partie de l’usage prĂ©vu de la librairie. -Choisissez cette approche lorsque la dĂ©finition de l’erreur doit rester stable, documentĂ©e, diagnosticable et indĂ©pendante du fait qu’un appelant la retourne ou la lĂšve. +Rien de tout cela ne change la mĂ©thode `Pay` ci-dessus : le transport reste lĂ©ger, et la connaissance durable de l’erreur vit Ă  cĂŽtĂ© de l’erreur, pas dans chaque site d’appel. ## Qu’est-ce qui change entre les approches ? @@ -120,10 +128,10 @@ Choisissez cette approche lorsque la dĂ©finition de l’erreur doit rester stabl | --- | --- | --- | --- | | Abstraction principale | valeur ou erreurs | rĂ©sultat avec raisons | erreur structurĂ©e | | Flux d’échec sous forme de valeur | central | central | disponible via `Outcome` | -| Erreurs ou raisons multiples | intĂ©grĂ© | intĂ©grĂ© | modĂ©lisĂ© via les erreurs internes ou une agrĂ©gation applicative | +| Erreurs ou raisons multiples | intĂ©grĂ© | intĂ©grĂ© | causes structurĂ©es ; l’agrĂ©gation d’erreurs indĂ©pendantes est Ă  la charge de l’application | | MĂ©tadonnĂ©es / faits propres Ă  l’occurrence | mĂ©tadonnĂ©es | mĂ©tadonnĂ©es | `ErrorContext` typĂ© | | SĂ©paration dĂ©diĂ©e entre messages publics et internes | dĂ©finie par l’application | dĂ©finie par l’application | explicite dans le modĂšle central | -| Transport de la mĂȘme erreur sous forme d’exception typĂ©e | pas le modĂšle principal | pas le modĂšle principal | intĂ©grĂ© via `ToException()` | +| Transport par exception depuis la mĂȘme dĂ©finition d’erreur | pas le modĂšle principal | pas le modĂšle principal | intĂ©grĂ© via `ToException()` — une exception structurĂ©e et typĂ©e par catĂ©gorie | | Taxonomie domaine / infrastructure / ports (frontiĂšres entrantes/sortantes) | dĂ©finie par l’application | dĂ©finie par l’application | intĂ©grĂ©e | | Transience (retenter peut-il rĂ©ussir ?) et direction de l’interaction (entrante ou sortante) | dĂ©finies par l’application | dĂ©finies par l’application | intĂ©grĂ©es pour les erreurs d’infrastructure | | Documentation humaine gĂ©nĂ©rĂ©e | hors du pĂ©rimĂštre principal de la librairie | hors du pĂ©rimĂštre principal de la librairie | intĂ©grĂ©e | From 59aae63f233dd8e091c22048b337d7228ce146b3 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 15 Jul 2026 23:02:31 +0000 Subject: [PATCH 07/10] docs: tighten the comparison intro and sharpen two phrasings - Split the long introductory paragraph into three, so the scenario's acknowledged bias reads more clearly. - Frame the named factory as the recommended usage rather than a technical requirement (DomainError.Create can be called inline), and gloss "transport" on first use. - Say the durable knowledge lives with the error's definition, not "beside the error". --- doc/ComparisonWithOtherLibraries.en.md | 10 +++++++--- doc/ComparisonWithOtherLibraries.fr.md | 10 +++++++--- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/doc/ComparisonWithOtherLibraries.en.md b/doc/ComparisonWithOtherLibraries.en.md index 5217d9d..f7c26d2 100644 --- a/doc/ComparisonWithOtherLibraries.en.md +++ b/doc/ComparisonWithOtherLibraries.en.md @@ -7,7 +7,11 @@ ErrorOr, FluentResults, and FirstClassErrors all help applications represent failure explicitly, but they optimize for different primary goals. -This page does not try to rank them in general. The scenario below deliberately emphasizes error stability, diagnosis, and documentation — the primary focus of FirstClassErrors — so it plays to its strengths; other scenarios, such as heavy multi-error validation or intensive functional composition, can naturally favor ErrorOr or FluentResults. Within this scenario, it shows the same situation through three different centres of gravity so you can choose the model that best matches your system. +This page does not try to rank them in general. + +The scenario below deliberately emphasizes error stability, diagnosis, and documentation: that is the primary focus of FirstClassErrors, so it naturally plays to its strengths. Other scenarios, such as heavy multi-error validation or intensive functional composition, can favor ErrorOr or FluentResults. + +The goal is to show the same situation through three different centres of gravity, so you can choose the model that best matches your system. ## The scenario @@ -67,7 +71,7 @@ Choose this style when the result and its reason graph are the primary abstracti ## FirstClassErrors: an error model with several transports -FirstClassErrors centres the API on the error itself. A named factory creates the error; `Outcome` (the library's success-or-failure result type) is one way it travels: +FirstClassErrors centres the API on the error itself. In the recommended usage, a named factory defines and creates the error; an `Outcome` (the library's success-or-failure result type) is one way to carry — or transport — that error as a value: ```csharp public Outcome Pay(Order order) @@ -120,7 +124,7 @@ throw PaymentError The error can additionally be linked to structured documentation describing its title, rule, possible causes, analysis leads, and examples. The generated catalog (a human-readable reference of every documented error) and the versioning workflow that guards it against breaking changes are part of the library's intended use. -None of this changes the `Pay` method above: the transport stays small, and the durable error knowledge lives beside the error, not in each call site. +None of this changes the `Pay` method above: the transport stays small, and the durable knowledge lives with the error's definition, not in each call site. ## What changes between the approaches? diff --git a/doc/ComparisonWithOtherLibraries.fr.md b/doc/ComparisonWithOtherLibraries.fr.md index d262cff..2898ff4 100644 --- a/doc/ComparisonWithOtherLibraries.fr.md +++ b/doc/ComparisonWithOtherLibraries.fr.md @@ -7,7 +7,11 @@ ErrorOr, FluentResults et FirstClassErrors permettent toutes de reprĂ©senter explicitement un Ă©chec, mais elles optimisent des besoins principaux diffĂ©rents. -Cette page ne cherche pas Ă  Ă©tablir un classement gĂ©nĂ©ral. Le scĂ©nario ci-dessous met volontairement l’accent sur la stabilitĂ©, le diagnostic et la documentation des erreurs — le pĂ©rimĂštre principal de FirstClassErrors — et joue donc en sa faveur ; d’autres scĂ©narios, comme la validation multiple intensive ou la composition fonctionnelle poussĂ©e, peuvent naturellement favoriser ErrorOr ou FluentResults. Dans ce scĂ©nario, elle montre une mĂȘme situation Ă  travers trois centres de gravitĂ© afin de choisir le modĂšle qui correspond rĂ©ellement au systĂšme. +Cette page ne cherche pas Ă  Ă©tablir un classement gĂ©nĂ©ral. + +Le scĂ©nario ci-dessous met volontairement l’accent sur la stabilitĂ©, le diagnostic et la documentation des erreurs : il correspond donc au pĂ©rimĂštre principal de FirstClassErrors et joue naturellement en sa faveur. D’autres scĂ©narios, comme la validation multiple intensive ou la composition fonctionnelle poussĂ©e, peuvent favoriser ErrorOr ou FluentResults. + +L’objectif est de montrer une mĂȘme situation Ă  travers trois centres de gravitĂ© afin de choisir le modĂšle qui correspond rĂ©ellement au systĂšme. ## Le scĂ©nario @@ -67,7 +71,7 @@ Choisissez cette approche lorsque le rĂ©sultat et son graphe de raisons sont l ## FirstClassErrors : un modĂšle d’erreur avec plusieurs transports -FirstClassErrors place l’erreur elle-mĂȘme au centre. Une factory nommĂ©e crĂ©e l’erreur ; `Outcome` (le type rĂ©sultat succĂšs-ou-Ă©chec de la bibliothĂšque) est une façon de la faire voyager : +FirstClassErrors place l’erreur elle-mĂȘme au centre. Dans l’usage recommandĂ©, une factory nommĂ©e dĂ©finit et crĂ©e l’erreur ; `Outcome` (le type rĂ©sultat succĂšs-ou-Ă©chec de la bibliothĂšque) est une façon de faire circuler — ou de transporter — l’erreur comme une valeur : ```csharp public Outcome Pay(Order order) @@ -120,7 +124,7 @@ throw PaymentError L’erreur peut en outre ĂȘtre liĂ©e Ă  une documentation structurĂ©e dĂ©crivant son titre, sa rĂšgle, ses causes possibles, ses pistes d’analyse et ses exemples. Le catalogue gĂ©nĂ©rĂ© (une rĂ©fĂ©rence lisible de toutes les erreurs documentĂ©es) et le workflow de versionnage qui le protĂšge des changements cassants font partie de l’usage prĂ©vu de la librairie. -Rien de tout cela ne change la mĂ©thode `Pay` ci-dessus : le transport reste lĂ©ger, et la connaissance durable de l’erreur vit Ă  cĂŽtĂ© de l’erreur, pas dans chaque site d’appel. +Rien de tout cela ne change la mĂ©thode `Pay` ci-dessus : le transport reste lĂ©ger, et la connaissance durable vit avec la dĂ©finition de l’erreur, pas dans chaque site d’appel. ## Qu’est-ce qui change entre les approches ? From a789b730824749424efd04aa93aabad87e2a6ca1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 15 Jul 2026 23:13:48 +0000 Subject: [PATCH 08/10] docs: use standard French term for 'library' and format Outcome MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace the false-friend "librairie" with the standard French "bibliothĂšque" across the comparison page and the two pages that link to it (documentation map, FAQ). The comparison page is retitled and the inbound navigation labels are updated to match. - Format the "Outcome" transport as the `Outcome` type in the decision guide, in both the English and French comparison pages. --- doc/ComparisonWithOtherLibraries.en.md | 2 +- doc/ComparisonWithOtherLibraries.fr.md | 14 +++++++------- doc/DocumentationMap.fr.md | 10 +++++----- doc/FAQ.fr.md | 2 +- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/ComparisonWithOtherLibraries.en.md b/doc/ComparisonWithOtherLibraries.en.md index f7c26d2..f7964de 100644 --- a/doc/ComparisonWithOtherLibraries.en.md +++ b/doc/ComparisonWithOtherLibraries.en.md @@ -162,7 +162,7 @@ Choose **FirstClassErrors** when: - errors are durable concepts used by developers, support, operations, or clients; - public and diagnostic messages must have explicit audiences; -- the same error must travel as data, an outcome, or an exception; +- the same error must travel as data, an `Outcome`, or an exception; - domain and infrastructure failures require different operational meaning; - generated documentation and compatibility checks are part of the requirement. diff --git a/doc/ComparisonWithOtherLibraries.fr.md b/doc/ComparisonWithOtherLibraries.fr.md index 2898ff4..52b0a46 100644 --- a/doc/ComparisonWithOtherLibraries.fr.md +++ b/doc/ComparisonWithOtherLibraries.fr.md @@ -1,4 +1,4 @@ -# Comparaison avec les librairies de gestion d’erreurs +# Comparaison avec les bibliothĂšques de gestion d’erreurs 🌍 **Langues :** 🇬🇧 [English](./ComparisonWithOtherLibraries.en.md) | đŸ‡«đŸ‡· Français (ce fichier) @@ -122,7 +122,7 @@ throw PaymentError .ToException(); ``` -L’erreur peut en outre ĂȘtre liĂ©e Ă  une documentation structurĂ©e dĂ©crivant son titre, sa rĂšgle, ses causes possibles, ses pistes d’analyse et ses exemples. Le catalogue gĂ©nĂ©rĂ© (une rĂ©fĂ©rence lisible de toutes les erreurs documentĂ©es) et le workflow de versionnage qui le protĂšge des changements cassants font partie de l’usage prĂ©vu de la librairie. +L’erreur peut en outre ĂȘtre liĂ©e Ă  une documentation structurĂ©e dĂ©crivant son titre, sa rĂšgle, ses causes possibles, ses pistes d’analyse et ses exemples. Le catalogue gĂ©nĂ©rĂ© (une rĂ©fĂ©rence lisible de toutes les erreurs documentĂ©es) et le workflow de versionnage qui le protĂšge des changements cassants font partie de l’usage prĂ©vu de la bibliothĂšque. Rien de tout cela ne change la mĂ©thode `Pay` ci-dessus : le transport reste lĂ©ger, et la connaissance durable vit avec la dĂ©finition de l’erreur, pas dans chaque site d’appel. @@ -138,10 +138,10 @@ Rien de tout cela ne change la mĂ©thode `Pay` ci-dessus : le transport reste lĂ© | Transport par exception depuis la mĂȘme dĂ©finition d’erreur | pas le modĂšle principal | pas le modĂšle principal | intĂ©grĂ© via `ToException()` — une exception structurĂ©e et typĂ©e par catĂ©gorie | | Taxonomie domaine / infrastructure / ports (frontiĂšres entrantes/sortantes) | dĂ©finie par l’application | dĂ©finie par l’application | intĂ©grĂ©e | | Transience (retenter peut-il rĂ©ussir ?) et direction de l’interaction (entrante ou sortante) | dĂ©finies par l’application | dĂ©finies par l’application | intĂ©grĂ©es pour les erreurs d’infrastructure | -| Documentation humaine gĂ©nĂ©rĂ©e | hors du pĂ©rimĂštre principal de la librairie | hors du pĂ©rimĂštre principal de la librairie | intĂ©grĂ©e | -| VĂ©rification de compatibilitĂ© du catalogue | hors du pĂ©rimĂštre principal de la librairie | hors du pĂ©rimĂštre principal de la librairie | intĂ©grĂ©e | +| Documentation humaine gĂ©nĂ©rĂ©e | hors du pĂ©rimĂštre principal de la bibliothĂšque | hors du pĂ©rimĂštre principal de la bibliothĂšque | intĂ©grĂ©e | +| VĂ©rification de compatibilitĂ© du catalogue | hors du pĂ©rimĂštre principal de la bibliothĂšque | hors du pĂ©rimĂštre principal de la bibliothĂšque | intĂ©grĂ©e | -« DĂ©fini par l’application » ou « hors du pĂ©rimĂštre principal » ne signifie pas impossible. Cela signifie que la prĂ©occupation n’est pas l’abstraction centrale de la librairie et qu’elle peut ĂȘtre prise en charge par des conventions applicatives ou un outillage externe. +« DĂ©fini par l’application » ou « hors du pĂ©rimĂštre principal » ne signifie pas impossible. Cela signifie que la prĂ©occupation n’est pas l’abstraction centrale de la bibliothĂšque et qu’elle peut ĂȘtre prise en charge par des conventions applicatives ou un outillage externe. ## Guide de dĂ©cision @@ -162,13 +162,13 @@ Choisissez **FirstClassErrors** lorsque : - les erreurs sont des concepts durables utilisĂ©s par les dĂ©veloppeurs, le support, l’exploitation ou les clients ; - les messages publics et de diagnostic doivent avoir des audiences explicites ; -- une mĂȘme erreur doit circuler comme donnĂ©e, outcome ou exception ; +- une mĂȘme erreur doit circuler comme donnĂ©e, `Outcome` ou exception ; - les Ă©checs mĂ©tier et infrastructurels doivent porter un sens opĂ©rationnel diffĂ©rent ; - la documentation gĂ©nĂ©rĂ©e et les contrĂŽles de compatibilitĂ© font partie du besoin. ## Une combinaison peut aussi ĂȘtre valable -Ces choix ne sont pas toujours exclusifs. Une application peut utiliser une librairie de rĂ©sultat gĂ©nĂ©raliste Ă  certaines frontiĂšres tout en conservant un catalogue d’erreurs documentĂ© sĂ©parĂ©. +Ces choix ne sont pas toujours exclusifs. Une application peut utiliser une bibliothĂšque de rĂ©sultat gĂ©nĂ©raliste Ă  certaines frontiĂšres tout en conservant un catalogue d’erreurs documentĂ© sĂ©parĂ©. Avant de combiner les modĂšles, dĂ©cidez quel type possĂšde l’identitĂ© stable de l’erreur. Dupliquer les codes, les messages, les mĂ©tadonnĂ©es et les mappings entre deux modĂšles concurrents crĂ©e gĂ©nĂ©ralement plus de travail que cela n’en Ă©conomise. diff --git a/doc/DocumentationMap.fr.md b/doc/DocumentationMap.fr.md index dbeea9b..0d57eb7 100644 --- a/doc/DocumentationMap.fr.md +++ b/doc/DocumentationMap.fr.md @@ -7,14 +7,14 @@ La documentation de FirstClassErrors est organisĂ©e selon **l’intention du lec Partez de la question Ă  laquelle vous cherchez Ă  rĂ©pondre. Chaque page principale peut ensuite renvoyer vers des guides ou des rĂ©fĂ©rences plus spĂ©cialisĂ©s. -## Je dĂ©couvre la librairie +## Je dĂ©couvre la bibliothĂšque Suivez ce parcours pour dĂ©terminer si FirstClassErrors correspond Ă  votre application. -1. [Premiers pas](GettingStarted.fr.md) — installer la librairie, crĂ©er une erreur et gĂ©nĂ©rer un premier catalogue d’erreurs lisible par des humains. +1. [Premiers pas](GettingStarted.fr.md) — installer la bibliothĂšque, crĂ©er une erreur et gĂ©nĂ©rer un premier catalogue d’erreurs lisible par des humains. 2. [Principes de conception](DesignPrinciples.fr.md) — comprendre pourquoi l’erreur est le modĂšle et pourquoi sa façon de voyager (exception ou valeur de retour) est un choix sĂ©parĂ©. -3. [Quand ne pas utiliser FirstClassErrors](WhenNotToUseFirstClassErrors.fr.md) — reconnaĂźtre les situations oĂč la librairie apporterait plus de formalisme que de valeur. -4. [Comparaison avec les librairies de gestion d’erreurs](ComparisonWithOtherLibraries.fr.md) — comparer FirstClassErrors, ErrorOr et FluentResults Ă  partir d’un mĂȘme scĂ©nario concret. +3. [Quand ne pas utiliser FirstClassErrors](WhenNotToUseFirstClassErrors.fr.md) — reconnaĂźtre les situations oĂč la bibliothĂšque apporterait plus de formalisme que de valeur. +4. [Comparaison avec les bibliothĂšques de gestion d’erreurs](ComparisonWithOtherLibraries.fr.md) — comparer FirstClassErrors, ErrorOr et FluentResults Ă  partir d’un mĂȘme scĂ©nario concret. ## Je dois comprendre le modĂšle @@ -93,7 +93,7 @@ Les erreurs applicatives doivent ĂȘtre crĂ©Ă©es via des factories nommĂ©es. Voir le Guide d’écriture des erreurs et les Bonnes pratiques. ``` -Les conventions locales restent ainsi courtes, tandis que la documentation de la librairie peut Ă©voluer sans crĂ©er plusieurs explications contradictoires. +Les conventions locales restent ainsi courtes, tandis que la documentation de la bibliothĂšque peut Ă©voluer sans crĂ©er plusieurs explications contradictoires. --- diff --git a/doc/FAQ.fr.md b/doc/FAQ.fr.md index 0d7c77f..19a129b 100644 --- a/doc/FAQ.fr.md +++ b/doc/FAQ.fr.md @@ -15,7 +15,7 @@ Vous pourriez. Transporter l’`Error` de la bibliothĂšque dans un type rĂ©sulta `Outcome` est cette idĂ©e, spĂ©cialisĂ©e pour ce modĂšle d’erreur. Son cĂŽtĂ© Ă©chec est toujours une `Error` — et non un second paramĂštre de type Ă  propager dans chaque signature — et sa petite API (`Then`, `Recover`, `Finally`) est nommĂ©e par intention plutĂŽt qu’avec la mĂ©canique de la programmation fonctionnelle (`Map`, `Bind`, `Match`). L’objectif : du code de domaine et des use cases qui se lisent comme un flux mĂ©tier, pas comme de la tuyauterie de rĂ©sultat gĂ©nĂ©rique. -Voir [Cas d’usage](UsagePatterns.fr.md) et [Comparaison avec les librairies de gestion d’erreurs](ComparisonWithOtherLibraries.fr.md). +Voir [Cas d’usage](UsagePatterns.fr.md) et [Comparaison avec les bibliothĂšques de gestion d’erreurs](ComparisonWithOtherLibraries.fr.md). ## Est-ce trop lourd pour une application simple ? From bde456d813a95a4246e7229ab58c5e0006c4e2b5 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 15 Jul 2026 23:31:06 +0000 Subject: [PATCH 09/10] docs: make the documentation map link real pages directly A map should know its own territory. Replace the three "any ... available in the current documentation version" pointers with direct links to pages that exist in the branch: - Error Taxonomy and Composition, under "understand the model"; - Integrate with structured logging, under "integrating delivery and operations"; - the Extraction and Project Discovery Reference, under "extending the documentation pipeline" and in the reference section. Also restructure for clarity: - Enrich the reference section (add the extraction reference; drop the FAQ, which is guidance, not a reference). - Add a "stuck or unsure about a decision" section gathering FAQ, Usage Patterns, When Not to Use, and the library comparison. - Present internationalization and analyzers as optional complements to writing an error rather than numbered mandatory steps. - Contrast the map with the README in the introduction. The English and French pages stay in sync. --- doc/DocumentationMap.en.md | 44 ++++++++++++++++++++++++-------------- doc/DocumentationMap.fr.md | 44 ++++++++++++++++++++++++-------------- 2 files changed, 56 insertions(+), 32 deletions(-) diff --git a/doc/DocumentationMap.en.md b/doc/DocumentationMap.en.md index 3fe80e2..64cc2bf 100644 --- a/doc/DocumentationMap.en.md +++ b/doc/DocumentationMap.en.md @@ -5,7 +5,9 @@ FirstClassErrors documentation is organized by **reader intent**, not by implementation namespace. -Start with the question you are trying to answer. Each primary page may link to more focused guides or references for advanced details. +The project README introduces the library and lists every document by area. This page is different: it helps you choose *what to read next* based on what you are trying to accomplish. + +Start with the question you are trying to answer. Each primary page then links to the focused guides and references you need for advanced details. ## I am discovering the library @@ -21,26 +23,26 @@ Follow this path when you are deciding whether FirstClassErrors fits your applic Use these pages before defining project-wide conventions. - [Core Concepts](CoreConcepts.en.md) — `Error`, factories, documentation, exceptions, and `Outcome`. +- [Error Taxonomy and Composition](ErrorTaxonomy.en.md) — domain, infrastructure, and port errors, and how errors nest as structured causes. - [Error Context Guide](ErrorContext.en.md) — structured facts attached to one occurrence. -- [Usage Patterns](UsagePatterns.en.md) — choose between exceptions, outcomes, domain errors, and infrastructure errors. - -The primary pages link to any dedicated taxonomy or composition guides available in the current documentation version. ## I am writing an error -Use this path when adding or reviewing an application error. +Use these pages when adding or reviewing an application error. + +- [Writing Errors Guide](WritingErrorsGuide.en.md) — code, title, description, rule, diagnostics, and examples. +- [Best Practices](BestPractices.en.md) — project and pull-request review checklist. -1. [Writing Errors Guide](WritingErrorsGuide.en.md) — code, title, description, rule, diagnostics, and examples. -2. [Best Practices](BestPractices.en.md) — project and pull-request review checklist. -3. [Internationalization](Internationalization.en.md) — localize public and documentation content while keeping stable identifiers invariant. -4. [Analyzer rules](analyzers/README.md) — understand the compile-time checks that protect the model and documentation links. +Then, as optional complements: + +- [Internationalization](Internationalization.en.md) — localize public and documentation content while keeping stable identifiers invariant. +- [Analyzer rules](analyzers/README.md) — the compile-time checks that protect the model and its documentation links. ## I am using errors in application code - [Usage Patterns](UsagePatterns.en.md) — select the right representation for common situations. - [Error Context Guide](ErrorContext.en.md) — attach useful, safe occurrence-level facts. - [Testing Guide](Testing.en.md) — assert outcomes and errors without manual plumbing. -- [FAQ](FAQ.en.md) — resolve common design questions and find the relevant focused guide. ## I am integrating delivery and operations @@ -49,23 +51,33 @@ Use this path when adding or reviewing an application error. 3. [Catalog Versioning — command reference](CatalogVersioningReference.en.md) — find exact CLI options and exit codes. 4. [Catalog Versioning — CI/CD integration](CatalogVersioningCI.en.md) — implement read-only contract checks in pipelines. -The operational integration pages link to any dedicated logging guidance available in the current documentation version. +To connect runtime failures back to the catalog: + +- [Integrate with structured logging](LoggingIntegration.en.md) — what to log, how to preserve inner errors, and how to link an occurrence to the generated catalog. ## I am extending the documentation pipeline - [Architecture of the Documentation Pipeline](ArchitectureOfTheDocumentationPipeline.en.md) — understand the end-to-end model and component responsibilities. +- [Extraction and Project Discovery Reference](DocumentationExtractionReference.en.md) — select projects and assemblies, configure isolated extraction, and handle its failures. - [Writing a custom renderer](WritingACustomRenderer.en.md) — implement and register another output format. - [Internationalization](Internationalization.en.md) — understand the extraction/rendering culture boundary. -The architecture page links to any focused extraction and project-discovery reference available in the current documentation version. - ## I need a reference, not a tutorial Use these pages when you already understand the model and need exact behavior. -- [Catalog Versioning command reference](CatalogVersioningReference.en.md) -- [Analyzer rules](analyzers/README.md) -- [FAQ](FAQ.en.md) +- [Extraction and Project Discovery Reference](DocumentationExtractionReference.en.md) — projects, assemblies, isolated extraction, and failure handling. +- [Catalog Versioning command reference](CatalogVersioningReference.en.md) — exact CLI options and exit codes. +- [Analyzer rules (FCExxx)](analyzers/README.md) — the full list of compile-time diagnostics. + +## I am stuck or unsure about a decision + +Use these pages when you need to make a design call or weigh options. + +- [FAQ](FAQ.en.md) — resolve common design questions and find the relevant focused guide. +- [Usage Patterns](UsagePatterns.en.md) — choose the right representation for a situation. +- [When Not to Use FirstClassErrors](WhenNotToUseFirstClassErrors.en.md) — recognize when the library adds more ceremony than value. +- [Comparison with error-handling libraries](ComparisonWithOtherLibraries.en.md) — compare FirstClassErrors with ErrorOr and FluentResults. ## Suggested team reading order diff --git a/doc/DocumentationMap.fr.md b/doc/DocumentationMap.fr.md index 0d57eb7..5293eb1 100644 --- a/doc/DocumentationMap.fr.md +++ b/doc/DocumentationMap.fr.md @@ -5,7 +5,9 @@ La documentation de FirstClassErrors est organisĂ©e selon **l’intention du lecteur**, et non selon les namespaces d’implĂ©mentation. -Partez de la question Ă  laquelle vous cherchez Ă  rĂ©pondre. Chaque page principale peut ensuite renvoyer vers des guides ou des rĂ©fĂ©rences plus spĂ©cialisĂ©s. +Le README du projet prĂ©sente la bibliothĂšque et recense les documents par domaine. Cette page est diffĂ©rente : elle vous aide Ă  choisir *quoi lire ensuite* selon ce que vous cherchez Ă  accomplir. + +Partez de la question Ă  laquelle vous cherchez Ă  rĂ©pondre. Chaque page principale renvoie ensuite vers les guides et rĂ©fĂ©rences spĂ©cialisĂ©s utiles. ## Je dĂ©couvre la bibliothĂšque @@ -21,26 +23,26 @@ Suivez ce parcours pour dĂ©terminer si FirstClassErrors correspond Ă  votre appl Lisez ces pages avant de dĂ©finir des conventions Ă  l’échelle d’un projet. - [Concepts fondamentaux](CoreConcepts.fr.md) — `Error`, factories, documentation, exceptions et `Outcome`. +- [Taxonomie et composition des erreurs](ErrorTaxonomy.fr.md) — erreurs de domaine, d’infrastructure et de ports, et comment les erreurs s’imbriquent en causes structurĂ©es. - [Guide du contexte d’erreur](ErrorContext.fr.md) — faits structurĂ©s propres Ă  une occurrence. -- [Cas d’usage](UsagePatterns.fr.md) — choisir entre exceptions, outcomes, erreurs de domaine et erreurs d’infrastructure. - -Les pages principales renvoient vers les Ă©ventuels guides dĂ©diĂ©s Ă  la taxonomie ou Ă  la composition disponibles dans la version courante de la documentation. ## J’écris une erreur -Utilisez ce parcours lors de l’ajout ou de la revue d’une erreur applicative. +Utilisez ces pages lors de l’ajout ou de la revue d’une erreur applicative. + +- [Guide d’écriture des erreurs](WritingErrorsGuide.fr.md) — code, titre, description, rĂšgle, diagnostics et exemples. +- [Bonnes pratiques](BestPractices.fr.md) — checklist de projet et de pull request. -1. [Guide d’écriture des erreurs](WritingErrorsGuide.fr.md) — code, titre, description, rĂšgle, diagnostics et exemples. -2. [Bonnes pratiques](BestPractices.fr.md) — checklist de projet et de pull request. -3. [Internationalisation](Internationalisation.fr.md) — localiser le contenu public et documentaire tout en gardant les identifiants stables invariants. -4. [RĂšgles d’analyse](analyzers/README.fr.md) — comprendre les contrĂŽles de compilation qui protĂšgent le modĂšle et les liens documentaires. +Puis, comme complĂ©ments facultatifs : + +- [Internationalisation](Internationalisation.fr.md) — localiser le contenu public et documentaire tout en gardant les identifiants stables invariants. +- [RĂšgles d’analyse](analyzers/README.fr.md) — les contrĂŽles de compilation qui protĂšgent le modĂšle et les liens documentaires. ## J’utilise les erreurs dans le code applicatif - [Cas d’usage](UsagePatterns.fr.md) — choisir la bonne reprĂ©sentation selon la situation. - [Guide du contexte d’erreur](ErrorContext.fr.md) — attacher des faits utiles, sĂ»rs et propres Ă  l’occurrence. - [Guide des tests](Testing.fr.md) — vĂ©rifier les outcomes et les erreurs sans plomberie manuelle. -- [FAQ](FAQ.fr.md) — rĂ©soudre les questions de conception courantes et trouver le guide spĂ©cialisĂ© pertinent. ## J’intĂšgre la livraison et l’exploitation @@ -49,23 +51,33 @@ Utilisez ce parcours lors de l’ajout ou de la revue d’une erreur applicative 3. [Versionnage du catalogue — rĂ©fĂ©rence des commandes](CatalogVersioningReference.fr.md) — retrouver les options exactes de la CLI et les codes de sortie. 4. [Versionnage du catalogue — intĂ©gration CI/CD](CatalogVersioningCI.fr.md) — mettre en place des contrĂŽles de contrat en lecture seule dans les pipelines. -Les pages d’intĂ©gration opĂ©rationnelle renvoient vers les Ă©ventuels guides dĂ©diĂ©s au logging disponibles dans la version courante de la documentation. +Pour relier les Ă©checs d’exĂ©cution au catalogue : + +- [IntĂ©gration au logging structurĂ©](LoggingIntegration.fr.md) — quoi logger, comment prĂ©server les erreurs internes et relier une occurrence au catalogue gĂ©nĂ©rĂ©. ## J’étends le pipeline documentaire - [Architecture du pipeline de documentation](ArchitectureOfTheDocumentationPipeline.fr.md) — comprendre le modĂšle de bout en bout et la responsabilitĂ© de chaque composant. +- [RĂ©fĂ©rence de l’extraction et de la dĂ©couverte des projets](DocumentationExtractionReference.fr.md) — sĂ©lectionner les projets et assemblies, configurer l’extraction isolĂ©e et traiter ses Ă©checs. - [Écrire son propre renderer](WritingACustomRenderer.fr.md) — implĂ©menter et enregistrer un nouveau format de sortie. - [Internationalisation](Internationalisation.fr.md) — comprendre la frontiĂšre de culture entre extraction et rendu. -La page d’architecture renvoie vers l’éventuelle rĂ©fĂ©rence dĂ©diĂ©e Ă  l’extraction et Ă  la dĂ©couverte des projets disponible dans la version courante de la documentation. - ## J’ai besoin d’une rĂ©fĂ©rence, pas d’un tutoriel Utilisez ces pages lorsque vous connaissez dĂ©jĂ  le modĂšle et recherchez un comportement exact. -- [RĂ©fĂ©rence des commandes de versionnage](CatalogVersioningReference.fr.md) -- [RĂšgles d’analyse](analyzers/README.fr.md) -- [FAQ](FAQ.fr.md) +- [RĂ©fĂ©rence de l’extraction et de la dĂ©couverte des projets](DocumentationExtractionReference.fr.md) — projets, assemblies, extraction isolĂ©e et traitement des Ă©checs. +- [RĂ©fĂ©rence des commandes de versionnage](CatalogVersioningReference.fr.md) — options exactes de la CLI et codes de sortie. +- [RĂšgles d’analyse (FCExxx)](analyzers/README.fr.md) — la liste complĂšte des diagnostics de compilation. + +## Je suis bloquĂ© ou j’hĂ©site sur une dĂ©cision + +Utilisez ces pages lorsque vous devez trancher une dĂ©cision de conception ou peser des options. + +- [FAQ](FAQ.fr.md) — rĂ©soudre les questions de conception courantes et trouver le guide spĂ©cialisĂ© pertinent. +- [Cas d’usage](UsagePatterns.fr.md) — choisir la bonne reprĂ©sentation selon la situation. +- [Quand ne pas utiliser FirstClassErrors](WhenNotToUseFirstClassErrors.fr.md) — reconnaĂźtre les situations oĂč la bibliothĂšque apporterait plus de formalisme que de valeur. +- [Comparaison avec les bibliothĂšques de gestion d’erreurs](ComparisonWithOtherLibraries.fr.md) — comparer FirstClassErrors, ErrorOr et FluentResults. ## Ordre de lecture conseillĂ© pour une Ă©quipe From c0103703d063ced7ee37ce9e5f1723490c52e3e2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 15 Jul 2026 23:36:03 +0000 Subject: [PATCH 10/10] docs: soften two intros on the documentation map - Say the primary pages point readers toward focused guides rather than asserting every page systematically links to them. - Frame "understand the model" for an individual reader too, not only for a team defining project-wide conventions. The English and French pages stay in sync. --- doc/DocumentationMap.en.md | 4 ++-- doc/DocumentationMap.fr.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/DocumentationMap.en.md b/doc/DocumentationMap.en.md index 64cc2bf..1df9e4a 100644 --- a/doc/DocumentationMap.en.md +++ b/doc/DocumentationMap.en.md @@ -7,7 +7,7 @@ FirstClassErrors documentation is organized by **reader intent**, not by impleme The project README introduces the library and lists every document by area. This page is different: it helps you choose *what to read next* based on what you are trying to accomplish. -Start with the question you are trying to answer. Each primary page then links to the focused guides and references you need for advanced details. +Start with the question you are trying to answer. The primary pages then point you toward the focused guides and references for advanced details. ## I am discovering the library @@ -20,7 +20,7 @@ Follow this path when you are deciding whether FirstClassErrors fits your applic ## I need to understand the model -Use these pages before defining project-wide conventions. +Read these pages to understand the model before defining your own usage or a project's conventions. - [Core Concepts](CoreConcepts.en.md) — `Error`, factories, documentation, exceptions, and `Outcome`. - [Error Taxonomy and Composition](ErrorTaxonomy.en.md) — domain, infrastructure, and port errors, and how errors nest as structured causes. diff --git a/doc/DocumentationMap.fr.md b/doc/DocumentationMap.fr.md index 5293eb1..f749388 100644 --- a/doc/DocumentationMap.fr.md +++ b/doc/DocumentationMap.fr.md @@ -7,7 +7,7 @@ La documentation de FirstClassErrors est organisĂ©e selon **l’intention du lec Le README du projet prĂ©sente la bibliothĂšque et recense les documents par domaine. Cette page est diffĂ©rente : elle vous aide Ă  choisir *quoi lire ensuite* selon ce que vous cherchez Ă  accomplir. -Partez de la question Ă  laquelle vous cherchez Ă  rĂ©pondre. Chaque page principale renvoie ensuite vers les guides et rĂ©fĂ©rences spĂ©cialisĂ©s utiles. +Partez de la question Ă  laquelle vous cherchez Ă  rĂ©pondre. Les pages principales vous orientent ensuite vers les guides et rĂ©fĂ©rences spĂ©cialisĂ©s utiles. ## Je dĂ©couvre la bibliothĂšque @@ -20,7 +20,7 @@ Suivez ce parcours pour dĂ©terminer si FirstClassErrors correspond Ă  votre appl ## Je dois comprendre le modĂšle -Lisez ces pages avant de dĂ©finir des conventions Ă  l’échelle d’un projet. +Lisez ces pages pour comprendre le modĂšle avant de dĂ©finir vos usages ou les conventions d’un projet. - [Concepts fondamentaux](CoreConcepts.fr.md) — `Error`, factories, documentation, exceptions et `Outcome`. - [Taxonomie et composition des erreurs](ErrorTaxonomy.fr.md) — erreurs de domaine, d’infrastructure et de ports, et comment les erreurs s’imbriquent en causes structurĂ©es.