Document that you should not overload promote_type directly (JuliaLan…

…g#41386)
johanmon · Jul 5, 2021 · 7822949 · 7822949
1 parent c37baaf
commit 7822949
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 2 deletions.
diff --git a/base/promotion.jl b/base/promotion.jl
@@ -223,6 +223,11 @@ Float16
 julia> promote_type(Int8, UInt16)
 UInt16
 ```
+
+!!! warning "Don't overload this directly"
+ To overload promotion for your own types you should overload [`promote_rule`](@ref).
+ `promote_type` calls `promote_rule` internally to determine the type.
+ Overloading `promote_type` directly can cause ambiguity errors.
 """
 function promote_type end
 

diff --git a/doc/src/manual/conversion-and-promotion.md b/doc/src/manual/conversion-and-promotion.md
@@ -319,9 +319,15 @@ julia> promote_type(Int8, Int64)
 Int64
 ```
 
+Note that we do **not** overload `promote_type` directly: we overload `promote_rule` instead.
+`promote_type` uses `promote_rule`, and adds the symmetry.
+Overloading it directly can cause ambiguity errrors.
+We overload `promote_rule` to define how things should be promoted, and we use `promote_type`
+to query that.
+
 Internally, `promote_type` is used inside of `promote` to determine what type argument values
-should be converted to for promotion. It can, however, be useful in its own right. The curious
-reader can read the code in [`promotion.jl`](https://github.com/JuliaLang/julia/blob/master/base/promotion.jl),
+should be converted to for promotion. The curious reader can read the code in
+[`promotion.jl`](https://github.com/JuliaLang/julia/blob/master/base/promotion.jl),
 which defines the complete promotion mechanism in about 35 lines.
 
 ### Case Study: Rational Promotions