Proposal: standardize expression to refer to functions with multiple arities (and ExDoc auto-linking)

[Fernando Tapia Rico]

Unfortunately, there isn’t a standard way to refer to functions with multiple arities in the documentation. That leads to inconsistencies: some places use an asterisk `fun/*`; others a list of arities separated by comma `fun/1,2`; others a list of arities separated by slashes `fun/1/2`; and others just the name of the function `fun`. 

Moreover, ExDoc’s auto-linking does not work with any of those expressions, loosing one of the features that I personally find really useful. In fact, that's how I was planning to encourage the usage of the agreed syntax.

After inspecting the Elixir codebase, I’ve found that `fun/1,2` is the most popular expression, and that seems the format used in the Erlang documentation. I'll go with that.

Regarding ExDoc, I would use the first arity to create the link (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`. I like this option because it allows developers to control were the link is going to point to. I’ve discarded the option of creating multiple anchors like `#fun/1,2` to avoid the combinatorial explosion of cases like `#fun/1,2,3,4`. 

As a final note, I'm not sure what to do regarding `fun/*` syntax. ExDoc could link to the function with lowest arity, but I would like to hear some opinions regarding that.

Thoughts?

[José Valim]

I don't think we should support `fun/*` because it implies any amount of arguments and I don't believe there is a single construct in Elixir that would allow that. While I would personally prefer `foo/1/2` (it feels like it conveys multiple arities better, but that's personal opinion), I will be happy to settle on `fun/1,2` too.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/e29c4e5d-0696-4645-821e-b2cca45fc722%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[OvermindDL1]

I'm a fan of `fun/1,2` or so, but not `fun/1/2` as that starts to look like a path and not a function link.

On Monday, October 1, 2018 at 2:01:14 PM UTC-6, José Valim wrote:

I don't think we should support `fun/*` because it implies any amount of arguments and I don't believe there is a single construct in Elixir that would allow that. While I would personally prefer `foo/1/2` (it feels like it conveys multiple arities better, but that's personal opinion), I will be happy to settle on `fun/1,2` too.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

On Mon, Oct 1, 2018 at 9:48 PM, Fernando Tapia Rico <fert...@gmail.com> wrote:

Unfortunately, there isn’t a standard way to refer to functions with multiple arities in the documentation. That leads to inconsistencies: some places use an asterisk `fun/*`; others a list of arities separated by comma `fun/1,2`; others a list of arities separated by slashes `fun/1/2`; and others just the name of the function `fun`. 

Moreover, ExDoc’s auto-linking does not work with any of those expressions, loosing one of the features that I personally find really useful. In fact, that's how I was planning to encourage the usage of the agreed syntax.

After inspecting the Elixir codebase, I’ve found that `fun/1,2` is the most popular expression, and that seems the format used in the Erlang documentation. I'll go with that.

Regarding ExDoc, I would use the first arity to create the link (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`. I like this option because it allows developers to control were the link is going to point to. I’ve discarded the option of creating multiple anchors like `#fun/1,2` to avoid the combinatorial explosion of cases like `#fun/1,2,3,4`. 

As a final note, I'm not sure what to do regarding `fun/*` syntax. ExDoc could link to the function with lowest arity, but I would like to hear some opinions regarding that.

Thoughts?

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

[José Valim]

Another advantage of comma is that there is less ambiguity, as `foo/2/4` may actually be an expression.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/2bd2fd3a-1ce9-40a0-965d-d5d1f9ee990e%40googlegroups.com.

[Steve Morin]

Definitely like `fun/1,2` better

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/2bd2fd3a-1ce9-40a0-965d-d5d1f9ee990e%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4KOwhm4FyvAZdxdrLu-j6wTS_qB-puGOF0%3DHYhS3q3Ukw%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Steve Morin | Hacker, Entrepreneur, Startup Advisor 

twitter.com/SteveMorin | stevemorin.com

Live the dream start a startup. Make the world ... a better place.

[László Bácsi]

Regarding ExDoc, I would use the first arity to create the link (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`. I like this option because it allows developers to control were the link is going to point to. I’ve discarded the option of creating multiple anchors like `#fun/1,2` to avoid the combinatorial explosion of cases like `#fun/1,2,3,4`. 

Would we use this for functions with default arguments too or only for custom multiple-arity functions which relate to each other?

I think most of the multiple-arity functions will end up being functions with default arguments where the documentation is attached to the largest arity function. Therefore, I would recommend using the largest arity in that case. We could still use `Module.fun/3,1,2`, but I would prefer `Module.fun/1,2,3`. What do you think?

 

[Fernando Tapia Rico]

Would we use this for functions with default arguments too or only for custom multiple-arity functions which relate to each other?

Just for the latter, but good catch!

To give more examples, I wouldn't use the new syntax with `Map.get/3`, but I'll definitely use it for `Task.async/1,3` (when needed).

[László Bácsi]

On Thu, Oct 4, 2018 at 1:04 PM Fernando Tapia Rico <fert...@gmail.com> wrote:

Would we use this for functions with default arguments too or only for custom multiple-arity functions which relate to each other?

Just for the latter, but good catch!

To give more examples, I wouldn't use the new syntax with `Map.get/3`, but I'll definitely use it for `Task.async/1,3` (when needed).

In that case it all makes sense and I like the proposal. :)  

[Christopher Keele]

My 2 cents: when faced with this in the past I've leaned on the syntax employed in multi-module aliasing, ie

Foo.bar/{1, 2}

I like the consistency. It just occurred to me that the parenthetical approach of this could be conducive to supporting ranges as well, such as

Foo.bar/{1..3}

[eksperimental]

Thanks for bring this up, as I thought the same way.
Also we need to add support for this in ExDoc.

I'm all for using ",".
I have also found myself using Mod.fun/1-3
when refering to functions with default arguments.
I find it cleaner than using commas when referring to the same function with default args


On Mon, 1 Oct 2018 12:48:39 -0700 (PDT)

Fernando Tapia Rico <fert...@gmail.com> wrote:

> Unfortunately, there isn’t a standard way to refer to functions with
> multiple arities in the documentation. That leads to inconsistencies: some
> places use an asterisk `fun/*`

> <https://github.com/elixir-lang/elixir/blob/master/lib/mix/lib/mix/config.ex#L15>;

> others a list of arities separated by comma `fun/1,2`

> <https://github.com/elixir-lang/elixir/blob/master/lib/elixir/test/elixir/string_test.exs#L29>;

> others a list of arities separated by slashes `fun/1/2

> <https://github.com/elixir-lang/elixir/blob/master/lib/elixir/pages/Compatibility%20and%20Deprecations.md#table-of-deprecations>`;

> and others just the name of the function `fun`

> <https://github.com/elixir-lang/elixir/blob/master/lib/ex_unit/lib/ex_unit/case.ex#L24-L25>

> .
>
> Moreover, ExDoc’s auto-linking does not work with any of those expressions

> <https://hexdocs.pm/ex_unit/ExUnit.Callbacks.html#on_exit/2>, loosing one

> of the features that I personally find really useful. In fact, that's how I
> was planning to encourage the usage of the agreed syntax.
>
> After inspecting the Elixir codebase, I’ve found that `fun/1,2` is the most
> popular expression, and that seems the format used in the Erlang

> documentation <http://erlang.org/doc/man/io_lib.html#fwrite-2>. I'll go

[José Valim]

I think in some cases we skip arities. Maybe in the Task module, so we would have Task.start_link/1,3, which is not handled by 1-3. :)

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/20181020091333.0d4da8bd.eksperimental%40autistici.org.

[eksperimental]

Sorry, what I was trying to suggest was to support both styles.

Please keep me informed of the decision, so I can contribute a PR to ExDoc to support the feature.

On Sat, 20 Oct 2018 09:58:59 +0200
José Valim <jose....@plataformatec.com.br> wrote:

> I think in some cases we skip arities. Maybe in the Task module, so we
> would have Task.start_link/1,3, which is not handled by 1-3. :)
>
>

> *José Valim*

[José Valim]

One format is enough and less prone to confusion. :)

--

José Valim

[Fernando Tapia Rico]

I would like to revive this thread :)

Is anyone ok with `fun/1,2`? `fun/*` won't be supported.

[Wojtek Mach]

> Is anyone ok with `fun/1,2`? `fun/*` won't be supported.

I think this is already a pretty common way so definitely +1 from me on making it official.

[eksperimental]

Thanks Fernando for bringing this back to life.
I'm OK. Let's have an agreement so we can start supporting it in ExDoc and make the according
changes to core.

[Sven Gehring]

I would be ok with `fun/1,2` but I prefer Christopher's solution using `fun/{1,2}` since that notation is already used in the core on various occasions. 

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/20190813110430.52fabd61.eksperimental%40autistici.org.

[Fernando Tapia Rico]

Thanks everyone for your feedback!

I think everybody is ok with `fun/1,2`, so let's make it official! 

I've created issues in:

ExDoc: https://github.com/elixir-lang/ex_doc/issues/1079

Elixir: https://github.com/elixir-lang/elixir/issues/9295

On Tuesday, August 13, 2019 at 1:16:45 PM UTC+2, Sven Gehring wrote:

I would be ok with `fun/1,2` but I prefer Christopher's solution using `fun/{1,2}` since that notation is already used in the core on various occasions. 

On Tue, 13 Aug 2019 at 06:04, eksperimental <eksper...@autistici.org> wrote:

Thanks Fernando for bringing this back to life.
I'm OK. Let's have an agreement so we can start supporting it in ExDoc and make the according
changes to core.

On Sat, 10 Aug 2019 14:10:18 +0200
Wojtek Mach <woj...@wojtekmach.pl> wrote:

> > Is anyone ok with `fun/1,2`? `fun/*` won't be supported. 
>
> I think this is already a pretty common way so definitely +1 from me on making it official.
>

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.