From b4008aa1a0cdf5a2a5251fa2aebe8024607c7d0d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Beno=C3=AEt=20Richard?= <kolaru@hotmail.com>
Date: Mon, 11 May 2026 22:26:01 +0200
Subject: [PATCH 1/2] Complete Decoration docstring

---
 src/intervals/construction.jl | 37 +++++++++++++++++++++++++++++++++++
 src/intervals/intervals.jl    |  2 +-
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/src/intervals/construction.jl b/src/intervals/construction.jl
index b3c0b3204..2ca11aa2c 100644
--- a/src/intervals/construction.jl
+++ b/src/intervals/construction.jl
@@ -197,10 +197,24 @@ Base.convert(::Type{BareInterval{T}}, x::BareInterval) where {T<:NumTypes} =
 Enumeration constant for the types of interval decorations described in
 Section 11.2 of the IEEE Standard 1788-2015:
 - `com -> 4` (common): non-empty, continuous and bounded interval.
+    This is the best possible decoration, the computations that generated it
+    only involved operations that are well-defined, continuous and bounded.
 - `dac -> 3` (defined and continuous): non-empty and continuous interval.
+    This decoration means that the computation encountered some infinite values,
+    for example because it started from an unbound interval, e.g. `inv(interval(1, Inf))`.
 - `def -> 2` (defined): non-empty interval.
+    This decoration occurs when the computations used a non-continuous function,
+    typically when using a [`Piecewise`](@ref) function.
 - `trv -> 1` (trivial): meaningless interval.
+    Something wrong happen during the computation, generally an ill defined operation,
+    or an operation that returns the empty interval, e.g. `sqrt(interval(-10, -1))`.
 - `ill -> 0` (ill-formed): not an interval (NaI).
+    The returned object is not even an interval.
+    This is the equivalent of `Nan` for intervals.
+
+The decoration `com`, `dac` and `def` are considered safe,
+whereas `trv` and `ill` mean that something went wrong and no meaningful
+result could be return.
 """
 @enum Decoration begin
     ill = 0
@@ -211,6 +225,19 @@ Section 11.2 of the IEEE Standard 1788-2015:
 end
 # note: `isless`, and hence `<`, `min` and `max`, are automatically defined
 
+"""
+    decoration(x::BareInterval)
+
+Return the default decoration of a `BareInterval`.
+
+Since `BareInterval` does not cary decoration information,
+return the most optimistic one possible based on its value:
+- `trv` if the interval is empty
+- `dac` if the interval is unbounded
+- `com` otherwise
+
+See [`Decoration`](@ref) for more infomation.
+"""
 function decoration(x::BareInterval)
     isempty_interval(x) && return trv
     isunbounded(x) && return dac
@@ -275,6 +302,16 @@ function bareinterval(x::Interval)
     return x.bareinterval
 end
 bareinterval(::Type{T}, x::Interval) where {T} = bareinterval(T, bareinterval(x))
+
+"""
+    decoration(x::Interval)
+
+Return the decoration of interval x.
+
+Return the default decoration of a `BareInterval`.
+
+See [`Decoration`](@ref) for more infomation.
+"""
 decoration(x::Interval) = x.decoration
 decoration(x::Complex{<:Interval}) = min(decoration(real(x)), decoration(imag(x)))
 
diff --git a/src/intervals/intervals.jl b/src/intervals/intervals.jl
index e0e6c0dfd..280002eaa 100644
--- a/src/intervals/intervals.jl
+++ b/src/intervals/intervals.jl
@@ -1,6 +1,6 @@
 # Construction and composability with numbers
 include("construction.jl")
-    export BareInterval, bareinterval, decoration, ill, trv, def, dac, com,
+    export BareInterval, bareinterval, decoration, Decoration, ill, trv, def, dac, com,
         Interval, interval, isguaranteed, @interval, @I_str
 include("parsing.jl")
 include("real_interface.jl")

From ede672b2026b59364311c5aacc003517bc13a231 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Beno=C3=AEt=20Richard?= <kolaru@hotmail.com>
Date: Tue, 12 May 2026 09:53:31 +0200
Subject: [PATCH 2/2] Remove out of place sentence

---
 src/intervals/construction.jl | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/intervals/construction.jl b/src/intervals/construction.jl
index 2ca11aa2c..6a4f4ac06 100644
--- a/src/intervals/construction.jl
+++ b/src/intervals/construction.jl
@@ -308,8 +308,6 @@ bareinterval(::Type{T}, x::Interval) where {T} = bareinterval(T, bareinterval(x)
 
 Return the decoration of interval x.
 
-Return the default decoration of a `BareInterval`.
-
 See [`Decoration`](@ref) for more infomation.
 """
 decoration(x::Interval) = x.decoration