Documenter.jl: Allow named @ref to docstrings without backticks

[jebej]

You might sometimes want to link to a function without explicitly writing the function name. Currently, writing [some function](@ref somefunction) for a function named somefunction does not work.

[mbauman]

Bump!

Oh, how I would love to be able to do this. There are many times I really want to use better prose but attach a cross-link to a docstring. Is there really no [](@ref foo) syntax that can do this?

[mortenpi]

What works is [`this is foo`](@ref foo), where you can have an arbitrary string in the backticks. But it is weird that it would only work with backticks, so I agree that it would be great to generalize this.

The only issue I see is how would one distinguish the custom heading IDs from function references. But we could prioritize one over the other I guess -- first see if there is a header ID like that and, if not, look for a docstring.

So the algorithm could be

• If ref is a string (i.e. surrounded by "), treat it as a heading reference: [...](@ref "Header String")
• Check if the ref is a custom header ID: [...](@ref header-id)
• Check if the ref is a docstring: [...](@ref foo(::Int))

Could be a good hacktoberfest issue :wink:

[mateuszbaran]

Bump. I just had exactly this issue.