From 6ba623e95184a1d649702e32c82c52204c1257cf Mon Sep 17 00:00:00 2001
From: Udoh Jeremiah <98605632+udohjeremiah@users.noreply.github.com>
Date: Mon, 29 Aug 2022 10:19:14 +0100
Subject: [PATCH] Add some more info to `Base.@irrational` (#46525)

---
 base/irrationals.jl | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/base/irrationals.jl b/base/irrationals.jl
index d147034382842..b0af42e6e283a 100644
--- a/base/irrationals.jl
+++ b/base/irrationals.jl
@@ -170,6 +170,28 @@ round(x::Irrational, r::RoundingMode) = round(float(x), r)
 
 Define a new `Irrational` value, `sym`, with pre-computed `Float64` value `val`,
 and arbitrary-precision definition in terms of `BigFloat`s given by the expression `def`.
+
+An `AssertionError` is thrown when either `big(def) isa BigFloat` or `Float64(val) == Float64(def)`
+returns `false`.
+
+# Examples
+```jldoctest
+julia> Base.@irrational(twoπ, 6.2831853071795864769, 2*big(π))
+
+julia> twoπ
+twoπ = 6.2831853071795...
+
+julia> Base.@irrational sqrt2  1.4142135623730950488  √big(2)
+
+julia> sqrt2
+sqrt2 = 1.4142135623730...
+
+julia> Base.@irrational sqrt2  1.4142135623730950488  big(2)
+ERROR: AssertionError: big($(Expr(:escape, :sqrt2))) isa BigFloat
+
+julia> Base.@irrational sqrt2  1.41421356237309  √big(2)
+ERROR: AssertionError: Float64($(Expr(:escape, :sqrt2))) == Float64(big($(Expr(:escape, :sqrt2))))
+```
 """
 macro irrational(sym, val, def)
     esym = esc(sym)