# Using @ref with explicit signatures

**URL:** <https://discourse.julialang.org/t/using-ref-with-explicit-signatures/133444>\
**Category:** General Usage\
**Tags:** documenter\
**Created:** [October 26, 2025, 9:34pm UTC](https://discourse.julialang.org/t/using-ref-with-explicit-signatures/133444 "2025-10-26T21:34:40Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![andreasvarga](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/andreasvarga/32/11634_2.png) [@andreasvarga](https://discourse.julialang.org/u/andreasvarga)\
**Post date:** [October 26, 2025, 9:34pm UTC](https://discourse.julialang.org/t/using-ref-with-explicit-signatures/133444/1 "2025-10-26T21:34:41Z")

</div>

In the [FaultDetectionTools](https://github.com/andreasvarga/FaultDetectionTools.jl) package I have two functions called `emmsyn` with the distinct signatures:

```julia-auto

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,

```julia-auto
[`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.

---

<div class="post-metadata">

**Author:** ![matthias314](https://avatars.discourse-cdn.com/v4/letter/m/a88e4f/32.png) [@matthias314](https://discourse.julialang.org/u/matthias314)\
**Post date:** [October 26, 2025, 11:30pm UTC](https://discourse.julialang.org/t/using-ref-with-explicit-signatures/133444/2 "2025-10-26T23:30:41Z")

</div>

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

```julia-auto
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

> <https://github.com/JuliaLang/julia/pull/54324>
>
> This is an extension of #53824 (therefore also fixes #52669), where details on t…he issue can be found (and, related to this, a different area where the issue shows, namely when you try to include documentation for a particular method of a function, which is similarly impossible when type parameters are involved).
> The fix proposed there had two drawbacks:
> \- with it, it is no longer possible to discriminate between two constructor functions that differ only in the type parameters. This is remedied with this PR by adding the parameters of the constructor as a unique type to the front of the method signature.
> \- with it, constructors must specify type parameters explicitly. The previous behavior is restored with this PR, which allows to have the type parameters unspecified.
> However, I completely agree with @matthias314's analysis that in this way, it is impossible to make the distinction between existing types and parametric types (which cannot be done well during macro deconstruction). This is also an issue in the code currently in Base; any type parameter will always be seen as parametric. For this reason, I'd rather see this whole behavior disappear; in the end, you cannot write Julia code like this. Removing the \`if isempty\` would prevent such a usage. A kind of middle ground would be to allow the current behavior, but only if the type is constrained (because this would not be possible for existing types).
> 
> \---
> 
> UPDATE: several more issues are fixed by this:
> Fixes #29437
> Fixes #41601

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

```julia-auto
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

```

---

<div class="post-metadata">

**Author:** ![andreasvarga](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/andreasvarga/32/11634_2.png) [@andreasvarga](https://discourse.julialang.org/u/andreasvarga)\
**Post date:** [October 27, 2025, 10:09am UTC](https://discourse.julialang.org/t/using-ref-with-explicit-signatures/133444/3 "2025-10-27T10:09:53Z")

</div>

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

```julia-auto
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

```julia-auto
help?> emmsyn(::FDIModel, ::FDFilterIF)
help?> emmsyn(::FDIModel, ::FDIFilterIF)

```

show each only the one correct docstring!

But

```julia-auto
[`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.

---

<div class="post-metadata">

**Author:** ![matthias314](https://avatars.discourse-cdn.com/v4/letter/m/a88e4f/32.png) [@matthias314](https://discourse.julialang.org/u/matthias314)\
**Post date:** [October 27, 2025, 12:35pm UTC](https://discourse.julialang.org/t/using-ref-with-explicit-signatures/133444/4 "2025-10-27T12:35:00Z")

</div>

Have you tried the following form?

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

```

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

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [October 27, 2025, 12:39pm UTC](https://discourse.julialang.org/t/using-ref-with-explicit-signatures/133444/5 "2025-10-27T12:39:13Z")

</div>

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

```julia-auto
[`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

```julia-auto
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` .

---

<div class="post-metadata">

**Author:** ![matthias314](https://avatars.discourse-cdn.com/v4/letter/m/a88e4f/32.png) [@matthias314](https://discourse.julialang.org/u/matthias314)\
**Post date:** [October 27, 2025, 1:09pm UTC](https://discourse.julialang.org/t/using-ref-with-explicit-signatures/133444/6 "2025-10-27T13:09:52Z")

</div>

> [@kellertuer](#):
>
> The right signature for a method might still be a bit hard to find

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

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [October 27, 2025, 1:25pm UTC](https://discourse.julialang.org/t/using-ref-with-explicit-signatures/133444/7 "2025-10-27T13:25:12Z")

</div>

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