diff --git a/base/irrationals.jl b/base/irrationals.jl
index 4394d67169ac7..e1994048a143f 100644
--- a/base/irrationals.jl
+++ b/base/irrationals.jl
@@ -5,7 +5,16 @@
 """
     AbstractIrrational <: Real
 
-Number type representing an exact irrational value.
+Number type representing an exact irrational value, which is automatically rounded to the correct precision in
+arithmetic operations with other numeric quantities.
+
+Subtypes `MyIrrational <: AbstractIrrational` should implement at least `==(::MyIrrational, ::MyIrrational)`,
+`hash(x::MyIrrational, h::UInt)`, and `convert(::Type{F}, x::MyIrrational) where {F <: Union{BigFloat,Float32,Float64}}`.
+
+If a subtype is used to represent values that may occasionally be rational (e.g. a square-root type that represents `√n`
+for integers `n` will give a rational result when `n` is a perfect square), then it should also implement
+`isinteger`, `iszero`, `isone`, and `==` with `Real` values (since all of these default to `false` for
+`AbstractIrrational` types), as well as defining [`hash`](@ref) to equal that of the corresponding `Rational`.
 """
 abstract type AbstractIrrational <: Real end