Docstrings attached to signatures

Internals & Design
1

As part of Change signatures that help is showing (revive #25672, fix #20064) by thofma · Pull Request #29102 · JuliaLang/julia · GitHub and https://github.com/JuliaDocs/Documenter.jl/issues/839 I am digging a bit through the docsystem and hit a wall when trying to figure out how docstrings are paired up with signatures. Here is a simple example.

julia> module Mod 
         """A""" foo(::Int) = nothing
       
         """B""" foo(::Vector{T}) where {T} = nothing
       end

Now let’s look at the docstrings attached to the different methods of Mod.foo.

julia> Docs.meta(Mod)[Docs.Binding(Mod, :foo)].order
2-element Array{Type,1}:
 Tuple{Int64}                              
 Union{Tuple{Array{T,1}}, Tuple{T}} where T

I understand the first one, but I don’t understand the second one. Is this union intended? I would have thought that the signatures showing up there would be more similar to

julia> [ f.sig for f in methods(Mod.foo) ]
2-element Array{Type,1}:
 Tuple{typeof(Main.Mod.foo),Int64}             
 Tuple{typeof(Main.Mod.foo),Array{T,1}} where T

I am quite puzzled by this, so any help or pointers in the right direction are appreciated.

2

When the function signature is parameterized, the parameters are gathered too:

julia> module Mod 
           """A""" foo(x::T) where T = nothing
           """B""" foo(::Vector{T}) where {T} = nothing
       end
Main.Mod

julia> Docs.meta(Mod)[Docs.Binding(Mod, :foo)].order
2-element Array{Type,1}:
 Union{Tuple{T}, Tuple{T}} where T         
 Union{Tuple{Array{T,1}}, Tuple{T}} where T

julia> """ a """ foo(x::S, y::T) where {S,T} = nothing;
julia> """ b """ foo(x::S, y::T) where {T,S} = nothing;
julia> """ c """ foo(x::T, y::S) where {T,S} = nothing;
julia> """ d """ foo(x::T, y::S) where {S,T} = nothing;

julia> Docs.meta(Main)[Docs.Binding(Main, :foo)].order
4-element Array{Type,1}:
 Union{Tuple{T}, Tuple{S}, Tuple{S,T}} where T where S
 Union{Tuple{S}, Tuple{T}, Tuple{S,T}} where S where T
 Union{Tuple{S}, Tuple{T}, Tuple{T,S}} where S where T
 Union{Tuple{T}, Tuple{S}, Tuple{T,S}} where T where S
3

Thanks! Apparently the culprit is Docs.signature!, see https://github.com/JuliaLang/julia/issues/29437.