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. On Tue, 19 Jul 2016 14:16:07 +0300 Alexei Sholik <[email protected]> wrote: > 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. > > On Tue, Jul 19, 2016 at 1:41 AM, eksperimental > <[email protected]> wrote: > > > 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. > > > > -- > > 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 [email protected]. > > 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. > > > -- 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 [email protected]. 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.
