Feature Request: @see_also attribute

[eksperimental]

I have been craving for this feature for a long time.
I think it will help with a lot with things such as including
discoverability of functions or leading people in the right direction
with very little effort from the documentation side.

A @see_also (it could be named @related, or any other better name).

Let's say in Enum module

@spec at(t, index, default) :: element | default
@see_also [:fetch!/2, :fetch/2]
def at(enumerable, index, default \\ nil) do
case fetch(enumerable, index) do
{:ok, h} -> h
:error -> default
end
end

@spec filter(t, (element -> as_boolean(term))) :: list
@see_also :reject
def filter(enumerable, fun) when is_list(enumerable)
and is_function(fun, 1) do
...

ExDoc could take advantage of such feature, and automatically linked to
suggested functions.

[Andrea Leopardi]

What would be the advantage of writing something like "See also fetch/2..." at the end of the @doc? The functions would  be linked this way as well.

--
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/20160719054127.7a04ed2d.eksperimental%40autistici.org.
For more options, visit https://groups.google.com/d/optout.

--

Andrea Leopardi

an.le...@gmail.com

[Alexei Sholik]

ExDoc already supports auto-linking for modules and functions inside the docstring. See, for example, http://elixir-lang.org/docs/stable/elixir/Enum.html#filter/2.

[eksperimental]

Thank you Andread and Alexei for your answers.

Well, my ideas is a bit different than what we have now.
I think this information could appear in a less prominent space, at the
bottom of the documentation. For example in ExDoc could be at the bottom inside a small box, just
showing additional information. Right now "SEE ALSO" is a section
itself, and it can be in the middle of the documentation (followed by
the EXAMPLES section).

Benefits.
1. If used consistently across a project, readers get used to it, and
can discover new functions, specially if the project is big, such as
elixir.
and they can learn where to find the related functions, scrolling to
the bottom of the function.
Having a SEE ALSO section in every function we want to link to it would
be TOO MUCH.

2. we could back-link if we want to (that is link to
functions that link to the current functions)

3. search functions can take advantage of it. let's say in ExDoc I
search for "reject", right now results would be: "Enum.reject/2,
Stream.reject/2"
but they could also include: "Enum.filter/2, Stream.filter/2"

I feel there's still a gap for beginner and not so beginner to discover
functions.
Another nice addition would be the inclusion of a @keyword attribute
to help people finding keywords by common keywords..but that's
dicussion for another thread.

[Andrea Leopardi]

The only feature I see in the list that *could* be somehow useful (but still not straightforward to get right) is the back-linking, but I don't think it's worth the feature to be honest. I think the simplicity of just a s "See also" snippet in the documenation is definitely enough :)

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

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

--

Andrea Leopardi

an.le...@gmail.com