Ex_doc: Support function expressions with multiple arities `fun/1,2`

[fertapric]

As discussed in the Elixir mailing list.

The first arity in the expression should be the one used to create the link (the Erlang documentation seems to do the same). For example Module.fun/1,2 would link to Module.html#fun/1; and Module.fun/4,3 to Module.html#fun/4. This option allows developers to control were the link is going to point to.

cc @eksperimental

[josevalim]

@fertapric I am not a big fan of the inversed arity. The lack of standard will be confusing for readers. My suggestion is to always point to the last one and you can use a custom link if you want to change it.

[cybrox]

I could take a look at this. :)

@josevalim Regarding the _not having a standard_ part, I agree that always linking to the first or last makes sense. For consistency, would it make sense to sort the arities in ascending order, if a user chooses to write Module.fun/4,3 in their docs or would you just leave that as-is?

[fertapric]

For consistency, would it make sense to sort the arities in ascending order, if a user chooses to write Module.fun/4,3 in their docs or would you just leave that as-is?

@cybrox if we want to make the standard stricter and not support inversed arities (or random arities fun/2,1,3), then I would only link if the arities are in ascending order.

[fertapric]

@josevalim I suggested the first arity because:

• that's how it works in the Erlang documentation
• it feels more natural to scroll down to see the rest of arities than scrolling up

[cybrox]

@fertapric Agreed. Also, in a lot of cases the lowest arity version of a function is the "common" one. (e.g. fwrite/2 for the 'generic' behaviour, fwrite/3 for when you want to 'customize' it more)

[eksperimental]

We may not necessarily have only one link.

The way it should work IMO is to have different links but compact the links as much as possible. It should be based on the list of functions with arities that we see in the side bar and compact.

For instance, we get on the side bar for Enum:

• chunk_every/2
• chunk_every/4

So if we write Enum.chunk_every/2,4, then Enum.chunk_every/2 should link to Enum.html#chunk_every/2 and ,4 should link to Enum.html#chunk_every/4.

If we write Enum.chunk_every/3,4, then the whole text should link to Enum.chunk_every/4 (because /4 is what we have in the sidebar).

If we write Enum.chunk_every/2,3,4, then Enum.chunk_every/2 should link to Enum.html#chunk_every/2 and ,3,4 to Enum.html#chunk_every/4.

If we write Enum.chunk_every/4,3,2, then Enum.chunk_every/4,3 should link to Enum.html#chunk_every/4 and ,2 to Enum.html#chunk_every/2.

If we write Enum.chunk_every/1,2,3,4, then Enum.chunk_every/1 should not link to anything, ,2 should link to Enum.chunk_every/2, and ,3,4 to Enum.html#chunk_every/4.

but if we write Enum.chunk_every/2,3, then Enum.chunk_every/2 should link to Enum.html#chunk_every/2 and ,3 to Enum.html#chunk_every/3 just not to break the behaviour that we have in ExDoc` for links with single arity.

in the same fashion as in the previous examples, if we write Enum.chunk_every/4,2,3, then Enum.chunk_every/4 should link to Enum.html#chunk_every/4, ,2 should link to Enum.html#chunk_every/2, and ,3 should link to Enum.html#chunk_every/3.

[cybrox]

While I do see the benefit of this, I am personally not a huge fan of microscopic mouse movements changing a link target. Or rather, I can imagine this behaviour to be quite confusing for someone using the docs for the first time (especially when it does not always link to the exact arity clicked on because of optional parameters)

I think we could get away with something similar if ex_doc would show a dropdown when clicking on the whole Enum.chunk_every/2,3 that lets you select the target arity, but even then, this would be way more work (for the user) than just being redirected to the lowest arity and scrolling down.

[eksperimental]

It is not microscopic. That would be on a pixel level.
It is about accuracy.
When having multiple arities reader will learn that if you click on the arity it WILL take to the function with that arity. Just the anchor will be different as explained above.

The commin use case is to use the arities in ascending order, so if the reader clicks on the function name it will take you to the first function. If she wants to read one in particular, she can click on the arity.

I dont see it cofusing on the reader side. It's more confusing to click on number 5 and have to scroll all the way down because you were lead to arity 2.

[josevalim]

Let's link only the to the first one. Given there is no visual indication, I don't think people will expect that clicking on a particular number will take them elsewhere. But I am guessing and we can always collect feedback. So while we collect that, let's ship with the simplest one.

[cybrox]

I think this can be closed with the merge of #1080; I think we can open new issues if feedback / bug reports from the implementation should come in.