Wishlist: document method specificity rules

[timholy]

There are a number of situations in which Julia could choose to throw an ambiguity error, but instead establishes rules for prioritizing some types over others. In early "experimental" days the only real source for this information was the C code, but now that we're stabilizing it seems appropriate to document those rules. (Perhaps that documentation exists, but with a few-minute search I was unable to find it.)

Motivated by the question at https://discourse.julialang.org/t/method-dispatch-for-tuples/5925.

[llbit]

Here is a case of method specificity that I find puzzling and which does not seem to be explained in the current documentation:

foo(::Type{T}, x::T) where T = 1
foo(::Type{T}, x::Number) where {T<:Number} = 2

A call to foo(Int, 1) returns 2. My mental model of parameterized methods was that they were instantiated before dispatch/specificity but this seems to not be the case. I have not looked at the implementation.

[vchuravy]

Specificity comes before instantiation

julia> Tuple{Type{T}, T} where {T<:Number} <: Tuple{Type{T}, T} where {T}
true

julia> Tuple{Type{T}, T} where {T} <: Tuple{Type{T}, T} where {T<:Number}
false

e.g. foo(::Type{T}, x::T) where T = 1 is foo(::Type{T}, x::T) where {T<:Any} = 1 thus T<:Number is a more specific version.