docs: update and expand validation module documentation

Author: amaurigmartins

docs/src/validation.md

@@ -1,5 +1,13 @@
 # Validation module
 
+## Contents
+```@contents
+Pages = ["validation.md"]
+Depth = 3
+```
+
+---
+
 This section documents the validation framework used by component constructors. The design is deterministic, non‑magical, and trait‑driven. The flow is:
 
 ```julia
@@ -10,15 +18,15 @@ The **typed cores** accept **numbers only**. All proxy handling happens in the *
 
 ---
 
-## 1. Architecture
+## Architecture
 
-### 1.1 Pipeline
+### Pipeline
 
 * **`sanitize(::Type{T}, args::Tuple, kwargs::NamedTuple)`**
 
-  * Rejects wrong arities and enforces presence using `required_fields(T)`.
-  * Maps optional keywords using `keyword_fields(T)`.
-  * For `has_radii(T) == true`, checks admissibility of raw radius inputs with `is_radius_input(T, x)` (numbers by default; types may extend to allow proxies).
+  * Rejects wrong arities: exactly `length(required_fields(T))` positionals are expected; optionals must be passed as keywords listed in `keyword_fields(T)`.
+  * Maps positionals to names using `required_fields(T)`; merges keyword arguments; rejects unknown keywords.
+  * If `has_radii(T) == true`, checks admissibility of raw radius inputs with `is_radius_input(T, Val(:radius_in), x)` and `is_radius_input(T, Val(:radius_ext), x)`. The default accepts only real, non‑complex numbers; types may extend to allow proxies.
   * Returns a **raw** `NamedTuple`.
 
 * **`parse(::Type{T}, nt)`**
@@ -34,38 +42,38 @@ The **typed cores** accept **numbers only**. All proxy handling happens in the *
 
 * **`validate!(::Type{T}, args...; kwargs...)`**
 
-  * Orchestrates the pipeline.
-  * Converts `Base.Pairs` → `NamedTuple` once; do not pass `Pairs` to user extensions.
+  * Orchestrates the pipeline. Use this in all convenience constructors.
 
-### 1.2 Traits (configuration surface)
+### Traits (configuration surface)
 
 * `has_radii(::Type{T})::Bool` — enables the radii rule bundle and raw acceptance checks.
 * `has_temperature(::Type{T})::Bool` — enables finiteness check on `:temperature`.
 * `required_fields(::Type{T})::NTuple` — positional keys.
 * `keyword_fields(::Type{T})::NTuple` — keyword argument keys.
-* `is_radius_input(::Type{T}, x)::Bool` — raw admissibility predicate for radii inputs; extend to allow proxies.
+* `coercive_fields(::Type{T})::NTuple` — values that participate in type promotion and will be coerced (default: `required_fields ∪ keyword_fields`).
+* `is_radius_input(::Type{T}, Val(:field), x)::Bool` — raw admissibility predicate for radii inputs; extend to allow proxies by field.
 * `extra_rules(::Type{T})::NTuple{K,Rule}` — additional constraints appended to the generated bundle.
 
 **Import before extending**:
 
 ```julia
 import ..Validation: has_radii, has_temperature, required_fields, keyword_fields,
-                     is_radius_input, parse, extra_rules
+                     coercive_fields, is_radius_input, parse, extra_rules
 ```
 
 Failing to import will create shadow functions in your module; the engine will not see your methods.
 
 ---
 
-## 2. Rules
+## Rules
 
 Rules are small value types `struct <: Rule` with an `_apply(::Rule, nt, ::Type{T})` method. All rule methods must:
 
 * Read data from the **normalized** `NamedTuple` `nt`.
-* Throw `ArgumentError` for logical violations; `DomainError` for numerical domain violations (e.g., non‑finite).
+* Throw `ArgumentError` for logical violations; `DomainError` for numerical domain violations (non‑finite).
 * Avoid allocations; use `@inline` where appropriate.
 
-### 2.1 Standard rules
+### Standard rules
 
 * `Normalized(:field)` — field must be numeric post‑parse.
 * `Finite(:field)` — `isfinite` must hold.
@@ -75,11 +83,12 @@ Rules are small value types `struct <: Rule` with an `_apply(::Rule, nt, ::Type{
 * `Less(:a,:b)` — strict ordering `a < b`.
 * `LessEq(:a,:b)` — non‑strict ordering `a ≤ b`.
 * `IsA{M}(:field)` — type membership check.
+* `OneOf(:field, set)` — membership in a finite set.
 
-### 2.2 Extending with custom rules (pattern)
+### Custom rule pattern
 
 ```julia
-struct InRange{T} <: Rule
+struct InRange{T} <: Validation.Rule
     name::Symbol; lo::T; hi::T
 end
 
@@ -94,7 +103,7 @@ Attach via `extra_rules(::Type{X}) = (InRange(:alpha, 0.0, 1.0), ...)`.
 
 ---
 
-## 3. Reverse tutorial — [`LineCableModels.DataModel.Tubular`](@ref)
+## Example implementation — `DataModel.Tubular`
 
 **Typed core** (numbers only):
 
@@ -127,42 +136,33 @@ Validation.keyword_fields(::Type{Tubular}) = _OPT_TUBULAR
 ```julia
 Validation.is_radius_input(::Type{Tubular}, ::Val{:radius_in}, x::AbstractCablePart) = true
 Validation.is_radius_input(::Type{Tubular}, ::Val{:radius_ext}, x::Thickness) = true
+Validation.is_radius_input(::Type{Tubular}, ::Val{:radius_ext}, x::Diameter) = true
 ```
 
-Rationale: convenience constructors may accept layer objects or thickness/diameter wrappers; they are *raw* inputs and must be transformed.
+The inner radius may take an existing cable part (its `radius_ext`); the outer radius may take a `Thickness` or `Diameter` wrapper.
 
 **Extra rules**:
 
 ```julia
-Validation.extra_rules(::Type{Tubular}) = (
-    IsA{Material}(:material_props),)
+Validation.extra_rules(::Type{Tubular}) = (IsA{Material}(:material_props),)
 ```
 
-* `IsA{Material}` enforces the material argument type.
-
 **Parsing**:
 
 ```julia
 Validation.parse(::Type{Tubular}, nt) = begin
     rin, rex = _normalize_radii(Tubular, nt.radius_in, nt.radius_ext)
-    (; nt..., radius_in = rin, radius_ext = rex)
+    (; nt..., radius_in=rin, radius_ext=rex)
 end
 ```
 
-Rationale: centralizes radius proxy resolution and uncertainty semantics in one place. The output is numeric radii. After this step, the `Normalized` rules guarantee that rule checks run on numbers.
-
 **Convenience constructor**:
 
 ```julia
-function Tubular(radius_in, radius_ext, material_props; temperature = _DEFS_TUBULAR[1])
-    ntv = validate!(Tubular, radius_in, radius_ext, material_props; temperature)
-    T = resolve_T(ntv.radius_in, ntv.radius_ext, material_props, ntv.temperature)
-    return Tubular(coerce_to_T(ntv.radius_in, T), coerce_to_T(ntv.radius_ext, T),
-                   coerce_to_T(material_props, T), coerce_to_T(ntv.temperature, T))
-end
+@_ctor Tubular _REQ_TUBULAR _OPT_TUBULAR _DEFS_TUBULAR
 ```
 
-Rationale: forces all user entry through `validate!`, then hands a coherent, type‑promoted set of values to the numeric core.
+This expands to a weakly‑typed method that calls `validate!`, promotes using `_promotion_T`, coerces via `_coerced_args`, and delegates to the numeric core.
 
 **Failure modes intentionally trapped**:
 
@@ -173,98 +173,98 @@ Rationale: forces all user entry through `validate!`, then hands a coherent, typ
 
 ---
 
-## 4. Template for a New Component
-
-Use the following checklist as a copy/paste starting point. Replace `NewPart` and fields accordingly.
+## Template for a new component
 
 ```julia
 # 1) Numeric core (numbers only)
 function NewPart(a::T, b::T, material::Material{T}, temperature::T) where {T<:REALSCALAR}
-    # compute derived quantities, then construct
+    # compute derived, then construct
 end
 
 # 2) Trait config
-Validation.has_radii(::Type{NewPart}) = true            # if the type has radii
-Validation.has_temperature(::Type{NewPart}) = true      # if temperature is used
-Validation.field_order(::Type{NewPart}) = (:a, :b, :material)
+Validation.has_radii(::Type{NewPart}) = true
+Validation.has_temperature(::Type{NewPart}) = true
 Validation.required_fields(::Type{NewPart}) = (:a, :b, :material)
+Validation.keyword_fields(::Type{NewPart})  = (:temperature,)
 
 # 3) Raw acceptance (extend only what you intend to parse)
-Validation.is_radius_input(::Type{NewPart}, x::AbstractCablePart) = true
-Validation.is_radius_input(::Type{NewPart}, x::Thickness)        = true
-Validation.is_radius_input(::Type{NewPart}, x::Diameter)         = true
+Validation.is_radius_input(::Type{NewPart}, ::Val{:radius_in},  x::AbstractCablePart) = true
+Validation.is_radius_input(::Type{NewPart}, ::Val{:radius_ext}, x::Thickness)        = true
 
-# 4) Extra rules (append per‑type constraints)
+# 4) Extra rules
 Validation.extra_rules(::Type{NewPart}) = (
     IsA{Material}(:material),
-    # InRange(:alpha, 0.0, 1.0), IntegerField(:num_wires), etc.
 )
 
 # 5) Parsing (proxy → numeric)
 Validation.parse(::Type{NewPart}, nt) = begin
     a′, b′ = _normalize_radii(NewPart, nt.a, nt.b)
-    (; nt..., a = a′, b = b′)
+    (; nt..., a=a′, b=b′)
 end
 
-# 6) Convenience constructor — call validate!, then delegate to numeric core
-function NewPart(a, b, material; temperature = T₀)
-    ntv = validate!(NewPart, a, b, material; temperature)
-    T = resolve_T(ntv.a, ntv.b, material, ntv.temperature)
-    return NewPart(coerce_to_T(ntv.a, T), coerce_to_T(ntv.b, T),
-                   coerce_to_T(material, T), coerce_to_T(ntv.temperature, T))
-end
+# 6) Convenience constructor — generated
+@_ctor NewPart (:a, :b, :material) (:temperature,) (T₀,)
 ```
 
 ---
 
-## 5. Extending Traits
+## Extending traits
 
 Traits are just methods. Add traits only when behavior toggles; avoid proliferation.
 
-### 5.1 New feature flags
+### New feature flags
 
-Example: a shielding flag that enables a rule bundle for `:shield_thickness`.
+Example: a shielding flag with its own bundle.
 
 ```julia
-# Trait
 Validation.has_shield(::Type) = false
 Validation.has_shield(::Type{SomeType}) = true
-
-# Generated rule splice (in Validation, not per‑type)
-#   Extend `_rules` to inject `(Nonneg(:shield_thickness), Finite(:shield_thickness))` when `has_shield(T)`.
 ```
 
-### 5.2 New admissibility predicate
+Extend `_rules` inside `Validation` to splice the corresponding checks when `has_shield(T)` is true.
+
+### Field‑specific admissibility
 
-Example: accept `Symbol` values for a categorical option.
+If only `:radius_in` should accept proxies, extend the field‑tagged predicate:
 
 ```julia
-Validation.is_option(::Type{T}, x) where {T} = false           # default
-Validation.is_option(::Type{X}, ::Symbol) where {X} = true      # for type X
+Validation.is_radius_input(::Type{X}, ::Val{:radius_in},  p::AbstractCablePart) = true
+Validation.is_radius_input(::Type{X}, ::Val{:radius_ext}, ::AbstractCablePart)  = false
 ```
 
-Use in `sanitize` for key `:option` prior to parsing.
-
 ---
 
-## 6. Testing guidelines
+## Testing guidelines
 
 * Test arity: `()`, `(1)`, `(1,2)` → `ArgumentError`.
 * Test raw type rejections: strings, complex numbers.
-* Test proxy acceptance: prior layer objects, `Thickness`, `Diameter`.
-* Test parse correctness: outputs are numeric and respect uncertainty rules.
-* Test rule violations: negative radii, inverted radii, non‑finite values.
+* Test proxy acceptance: prior layer objects, `Thickness`, `Diameter` when allowed.
+* Test parse correctness: outputs numeric and respect uncertainty rules.
+* Test rule violations: negative radii, inverted radii, non‑finite values, invalid sets.
 * Test constructor round‑trip: convenience path and numeric core produce equivalent instances after coercion.
 
+## Usage notes
+
+* Keep all proxy handling in `parse`. Do not call normalizers in constructors.
+* Error messages must be terse and contextualized with the component type name.
+* Prefer tuple returns and `NamedTuple` updates to avoid allocations.
+* When adding rules, benchmark `_apply` implementations.
+
 ---
 
-## 7. Operational notes
+## API reference
 
-* Keep all proxy handling in `parse`. Do not call normalizers in constructors.
-* Keep error messages terse and contextualized with the component type name.
-* Prefer tuple returns and `NamedTuple` updates for zero‑allocation pipelines.
-* When adding rules, benchmark `_apply` methods; avoid dynamic dispatch inside rules.
+```@autodocs
+Modules = [LineCableModels.Validation]
+Order = [:module, :constant, :type, :function, :macro]
+Public = true
+Private = true
+```
 
 ---
 
-This framework is designed to be extended in small, explicit increments. If behavior changes, change the trait and the minimal corresponding code; the rest of the pipeline remains stable.
+## Index
+```@index
+Pages   = ["validation.md"]
+Order   = [:module, :constant, :type, :function, :macro]
+```