Ex_doc: Link to functions with custom text

[eksperimental]

I'm going thoroughly through the Elixir documentation, and I have come across quiet a common pattern, which is wanting to link to a function/callback without showing the full Module.function/arity thing. (most of the time trying to hide the module)... in this case because it's either Kernel or Kernel.SpecialForms and we don't need to distract the user with this information.

A good example is the Guards page.

the following “type-check” functions (all documented in the Kernel module):

• is_atom/1
• is_binary/1
• is_bitstring/1
• is_boolean/1

you want to link to Kernel.is_atom/1, but you don't want to show Kernel.

My proposal is to support:

[custom](`Module.functions_name/arity`)

and

[`function_name/arity`](`Module.functions_name/arity`)

and/or (not so sure about this last one)

`[function_name/arity](Module.functions_name/arity)`

what do you guys think?

[josevalim]

I think we should support this:

[...](Module.functions_name/arity)

What is inside square brackets shouldn't really matter. The example above has a small ambiguity, since it would match a page that looks like this Page.html/2 but those are uncommon and can be solved by using ./Page.html/2, so I think we should be fine?

[josevalim]

Actually, if we want to support modules:

[...](Module)

Then we should require backticks to avoid false positives but backticks feel weird in there. :S Plus there is also parsing ambiguities. For example, this is valid text:

see the main module (`Kernel`)

So we would need to be careful in the regex side. One option is to tell folks to link to it directly:

[...](Module.html#function_name/arity)

And the epub formatter could convert those back to epub links if it wants to.

[josevalim]

@eksperimental btw, please don't put "feature request" in the title and use the labels for that. It is easier to explore like that.

[eksperimental]

not using backticks in the parenthesis will lead to problems. people may want to link to a file, and that could be the same name as the module.

I don't think backticks are unnecessary in the parenthesis.
backticks convert:

• Kernel to Kernel.html
• Kernel.if/2 to Kernel.html#if/2
• ExUnit.Case.test/3 to http://elixir-lang.org/docs/stable/ex_unit/ExUnit.Case.html#test/3

so doing

[...](`Kernel.if/2`)

is the same as doing

[...](Kernel.html#if/2)

It is one less thing that we need to worry about, and it follows the same existing rules of formatting.

[michalmuskala]

I'm looking to make some changes in the Phoenix Endpoint documentation and this would be really helpful - the primary use case would be linking to the callback documentation while spelling out arguments, something like:

[`foo(a, b)`](`c:foo/2`)

[whatyouhide]

Should we proceed with any of the alternatives above? I agree that

[...](`MyModule`)

feels weird with the backticks but I can't really think of a better alternative 😕

[josevalim]

I think that's the way to go because anything else is pretty much ambiguous.

[ssboisen]

Sounds like a great addition, we plan to utilize ex doc to do our domain documentation. This would allow for a module specifying the ubiquitous language of our domain as functions and refer to those with a more readable name which make sense for business stakeholders.

[josevalim]

@ssboisen a PR will definitely be appreciated then!

[wojtekmach]

Blast from the past!

1st use case is already handled:

you want to link to Kernel.is_atom/1, but you don't want to show Kernel.

2nd use case:

[`foo(a, b)`](`c:foo/2`)

since it's a callback we need to be explicit. However for a regular function we _could_:

# make it so that:
`foo(a, b)`
# behaves like:
[`foo(a, b)`](`c:foo/2`)

and I think that'd be a win. (obviously it's gonna look nicer in IEx without extra cruft)

It's good to have custom links as escape hatch but perhaps some use cases we're currently using them for could be made available in other way? What are some other usages of custom links?

[josevalim]

I would personally like to avoid making our linking more and more complex. :)