Using @ref with explicit signatures

General Usage
1

In the FaultDetectionTools package I have two functions called emmsyn with the distinct signatures:


julia> methods(emmsyn)
# 2 methods for generic function "emmsyn" from FaultDetectionTools:
 [1] emmsyn(sysf::FDIModel{T1}, sysref::FDIFilterIF{T2}; poles, sdeg, smarg, nullspace, minimal, simple, regmin, normalize, freq, tcond, HDesign, offset, atol, atol1, atol2, atol3, rtol, fast) where {T1, T2}
     @ C:\Users\Andreas\Documents\software\Julia\FaultDetectionTools.jl\src\FDIsynthesis.jl:3762
 [2] emmsyn(sysf::FDIModel{T1}, sysr::Union{FDFilterIF{T2}, FDIModel{T2}}; poles, sdeg, smarg, nullspace, minimal, simple, regmin, normalize, freq, tcond, HDesign, offset, atol, atol1, atol2, atol3, rtol, fast) where {T1, T2}
     @ C:\Users\Andreas\Documents\software\Julia\FaultDetectionTools.jl\src\FDIsynthesis.jl:3183

I would like to build cross-references in the documentation to these functions using @ref . I tried in several ways, as for example,

[`emmsyn`](@ref)
[`emmsyn(::FDIModel, ::FDFilterIF)`](@ref)
[`emmsyn(::FDIModel, ::FDIFilterIF)`](@ref)

but all links go to the second function (which is the first one in the source code). I wonder if there is a way to also obtain a link to the first function. Many thanks in advance for your help.

2

The reason could be that Julia’s docstring search is broken in the presence of type parameters. Here is an example:

julia> "vec" f(v::Vector{T}) where T = 1;

julia> "set" f(v::Set{T}) where T = 2;

help?> f([1,2])  # shows docstrings for both functions

help?> f(Set([1,2]))  # shows docstrings for both functions

There are some PRs addressing this. The most recent one probably is

EDIT: A workaround is to separate the docstring from the function definition and to omit type parameters for the docstring (if possible):

julia> "vec" g(::Vector);

julia> g(v::Vector{T}) where T = 1;

julia> "set" g(::Set);

julia> g(v::Set{T}) where T = 2;

help?> g([1,2])  # shows only the first docstring
1 Like
3

Thanks for this hint. I was not aware that the help is also affected!

help?> emmsyn
help?> emmsyn(::FDIModel, ::FDFilterIF)
help?> emmsyn(::FDIModel, ::FDIFilterIF)

all show both docstrings. However, after inserting
emmsyn(::FDIModel, ::FDFilterIF)
and
emmsyn(::FDIModel, ::FDIFilterIF)
between the docstrings and the respective function definitions,
help?> emmsyn
shows both docstrings (as expected) and

help?> emmsyn(::FDIModel, ::FDFilterIF)
help?> emmsyn(::FDIModel, ::FDIFilterIF)

show each only the one correct docstring!

But

[`emmsyn(::FDIModel, ::FDFilterIF)`](@ref)
[`emmsyn(::FDIModel, ::FDIFilterIF)`](@ref)

continues to point to the same function, so apparently @ref doesn’t benefit of the above fix for help.

It seems that @ref points always to the first docstring in the source file.

4

Have you tried the following form?

[`emmsyn`](@ref emmsyn(::FDIModel, ::FDFilterIF))

I use something like that in my doc files, and it works.

1 Like
5

You can also refer to the specific method of a function in the round brackets after ref. For example

[`emmsyn(::FDIModel, ::FDFilterIF)`](@ref emmsyn(::FDIModel, ::FDFilterIF))

Then you can even use an arbitrary text upfront in the [...] in case you feel the types might look to technical. The right signature for a method might still be a bit hard to find. I recently used DocumenterInterlinks.jl to narrow then down a bit (even when not using Links between packages)

In theory this would look something like

using DocumenterInterLinks
links = InterLinks( "FaultDetectionTools" => ("https://andreasvarga.github.io/FaultDetectionTools.jl/stable/") )

just that in practice your last stable release is from a time before Documenter had the inventory necessary for this. With that you can nicely search for full signatures to put after @ref .

6

When the signature gets complicated, I copy-paste it verbatim from the function definition (or the docstring definition).

1 Like
7

That should usually also work, though with parameters, I encountered every now and then, that it was a bit tricky.