Docs are for wrong arity for functions called in 'pipeline' about elixir_sense

[msaraiva]

@kenny-evitt ElixirSense always returns both Enum.reduce/2 and Enum.reduce/3. Each function is supposed to be highlighted using a blockquote > and there should be a line between them.

The problem is that, depending on how the editor formats markdown, the blockquote might not be well emphasized, consequently it can be very hard to see the separation. The idea is that it should look something like the official Elixir docs https://hexdocs.pm/elixir/1.9.1/Enum.html#reduce. In practice, it doesn't because each editor applies its own formatting and indentation.

I experience the same problem in VSCode using ElixirLS.

@axelson, @JakeBecker @slashmili can the style be customized/fixed in the client? Otherwise, we could try to use something other than blockquotes. I'm open to suggestions here.

[kenny-evitt]

@msaraiva My bad! It didn't even occur to me to check whether the docs included all arities. Given that that's the case, I don't think there's any problem with the formatting. I just didn't notice that the docs had been combined because of the relatively short length of the window in which they were being shown.

But is it possible – or feasible – to determine the relevant arity and either only show the docs for that version of the function/macro, or provide some means by which clients could know where in the docs to navigate (i.e. a starting line for the relevant arity)?

I think the greatest part of my initial confusion was due to the offical/Hex docs clearly delineating among different arities as if they were independent:

• Enum — Elixir v1.9.1

One piece of evidence of that is that the fragment in your link doesn't seem to exist, i.e. there is no documentation for the reduce function, for all arities, apart from the docs for each specific form.

Another piece of evidence (that was probably not much of a reason) why I was confused is that @doc attributes are specific to an arity too:

• elixir/enum.ex at v1.9.1 · elixir-lang/elixir

[msaraiva]

But is it possible – or feasible – to determine the relevant arity and either only show the docs for that version of the function/macro, or provide some means by which clients could know where in the docs to navigate (i.e. a starting line for the relevant arity)?

It's possible to determine the arity as long as the code is complete. For incomplete code like:

Enum.reduce(list, 

Which one should we show? If both, then we still need to find a better way to present that to the user.

[axelson]

@msaraiva for any Language Server Protocol clients anything any valid markdown is supported so I think that blockquotes should be fine.

[kenny-evitt]

@msaraiva Maybe some examples would be helpful:

Complete code

Example 1

Enum.reduce(list, fun)

Show the arity two version.

Example 2

Enum.reduce(list, initial_acc, fun)

Show the arity three version.

Example 3

list
|> Enum.reduce(fun)

Show the arity two version.

Example 4

list
|> Enum.reduce(initial_acc, fun)

Show the arity three version.

Incomplete code

Example 5

ex_doc_target_function(

Show all versions.

Example 6

ex_doc_target_function(a

Show all versions with an arity of at least one.

Example 7

ex_doc_target_function(a,

Show all versions with an arity of at least two.

Example 8

ex_doc_target_function(a, b

Show all versions with an arity of at least two.

Example 9

ex_doc_target_function(a, b,

Show all versions with an arity of at least three.

Example 10

ex_doc_target_function(a, b, c

Show all versions with an arity of at least three.

Example 11

a
|> ex_doc_target_function(

Show all versions with an arity of at least one.

Example 12

a
|> ex_doc_target_function(b

Show all versions with an arity of at least two.

Example 13

a
|> ex_doc_target_function(b,

Show all versions with an arity of at least three.

Example 14

a
|> ex_doc_target_function(b, c

Show all versions with an arity of at least three.

[kenny-evitt]

@msaraiva @axelson As for the formatting itself, of the different arities, I think the current formatting is fine. I think something like this might be (very) marginally better:

## `Enum.reduce(enumerable, fun)`

... but that's just due to a cursory consideration of the 'semantics' of the Markdown itself (as it's not 'really' a quote so much as a header with code (or a code fragment)).

Interestingly, Enum.reduce is a good example of why it may not be worth changing this at all. Because @doc attributes are specific to a single arity version, there's no way to document info pertinent to all or multiple versions. And in the case of Enum.reduce/3, there's some interesting info in its documentation that wouldn't be visible if only the arity two docs were shown.

[josevalim]

Btw, @axelson, @JakeBecker @slashmili, a quick question: what formats would the editors accept to show documentation? Is it markdown only? Could it be HTML or something else?

[slashmili]

Regarding doc supports in VIM

• HTML: There is no out of the box HTML engine in vim(not sure if there is any plugin at all). Users will see html tags which is not nice.
• markdown: Since it's mainly text, it works for most of the cases!
• man format: I'm not sure if man is still relevant in the world that Visual Studio Code is taking over. In Alchemist.vim we are providing Erlang's module docs using erl -man <module>

[kenny-evitt]

@slashmili This question on the Vi and Vim Stack Exchange site concurs:

• external command - How to render html file? - Vi and Vim Stack Exchange

Basically, a text web browser like links, elinks, lynx, or w3m would be required to render HTML.

[axelson]

Btw, @axelson, @JakeBecker @slashmili, a quick question: what formats would the editors accept to show documentation? Is it markdown only? Could it be HTML or something else?

@josevalim markdown is definitely preferred since it is very easy to support (either fully or minimally as plaintext) in a wide range of editors. And since HTML is much more expressive in it's formatting capabilities it would become more difficult to adjust styling to fit well in different contexts (such as hover, vs. full docs). I believe that markdown is the most common format for this type of information for usage in editors at this time (besides plaintext).