Documenter.jl
Documenter.jl copied to clipboard
Docstring selected by `@ref` doesn't match result from `Base.@doc`
Consider the following (contrived) example:
module Tmp
"generic method"
function g(::Any, ::Any) end
"extra doc for specialized method"
g(::Real)
end # module
We define a single function and then add some extra documentation for a non-existing method
With a docs page:
```@meta
CurrentModule=Tmp
```
```@docs
g(::Any, ::Any)
g(::Real)
```
link1: [`g`](@ref g(::Any, ::Any))
link2: [`g`](@ref g(::Real))
link3: [`g`](@ref g(::Float64))
I would expect link1 to point to g(::Any, ::Any)
and links 2 and 3 to point to g(::Real)
, but the actual behavior is that links 1 and 3 point to g(::Any, ::Any)
and link 2 points to g(::Real)
This doesn't match the behavior of Base.@doc
:
julia> @doc Tmp.g(::Any, ::Any)
generic method
julia> @doc Tmp.g(::Real)
extra doc for specialized method
julia> @doc Tmp.g(::Float64)
extra doc for specialized method
However, if a method for g(::Real)
is actually defined (i.e. function g(::Real) end
), then things behave as expected.
So it seems like in the case that the method doesn't exist, the binding is only found if the signature matches exactly, which doesn't seem consistent with the case the method actually exists, nor with Base.@doc
I think the discussions in #839 might be relevant for this, even though they are more about at-docs blocks.
In fairness, I am not sure that the at-refs should match fuzzily at all. But linking to the 2-argument one is wrong either way.