Documenter.jl icon indicating copy to clipboard operation
Documenter.jl copied to clipboard

Docstring selected by `@ref` doesn't match result from `Base.@doc`

Open JackDunnNZ opened this issue 2 years ago • 1 comments

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

JackDunnNZ avatar Jul 20 '22 22:07 JackDunnNZ

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.

mortenpi avatar Jul 21 '22 03:07 mortenpi