[erlang-questions] Erlang documentation -- a modest proposal

[Loïc Hoguin]

On the "external tools":

As far as my workflow is concerned, the Erlang shell is nearly never 
used. So starting the shell to then look for the function I want is not 
as efficient as just opening a man page. Not to mention the lack of 
search and navigation, plus the fact I'd need to open a separate shell 
just to keep the documentation on-screen while using the shell further.

I've said it before, I don't think it's necessarily a bad idea to have 
interactive help in the shell, but it shouldn't replace other forms. 
Different formats are helpful to different people, and I think we should 
strive to provide as many options as possible to get to the 
documentation; not remove all of them just because of bad past decisions.

On 09/28/2016 11:33 AM, Michał Muskała wrote:
> While talking about Elixir documentation everybody seems to focus exclusively on the HTML docs. Surprisingly that's not the primary way of how I (and most of the people I know) interact with the documentation that Elixir provides - the primary way is the direct access to documentation from IEx.
>
> I guess that's in many ways similar to the access through man pages, but instead of using an external tool, it comes built-in right into the language itself. In the shell you can use the h/1 helper macro to access documentation on modules (h Kernel), all functions with a particular name (h Enum.reduce) or for a specific function with a particular arity (h Enum.reduce/3). Similarly there are helpers for accessing documentation on behaviours (b/1) and types (t/1). It works both for the standard library and the external packages. For those complaining about use of external tools - here you don't need any of them, only erlang/elixir - no lynx, no man, no browser. This has also a huge advantage of perfectly working offline - again for both the built-in modules as well as all the external dependencies in the exact same way. I cannot stress enough how valuable it is I can access documentation for all the modules I'm using in the same way.
>
> Here are some examples:
> https://www.dropbox.com/s/0eleru83ya6oscg/Screenshot%202016-09-28%2011.29.10.png?dl=0
> https://www.dropbox.com/s/x8hg3qyfje0jpmc/Screenshot%202016-09-28%2011.29.53.png?dl=0
> https://www.dropbox.com/s/8c15as0cvu46gy0/Screenshot%202016-09-28%2011.31.27.png?dl=0
> https://www.dropbox.com/s/0xrqtuhjblixnjb/Screenshot%202016-09-28%2011.32.33.png?dl=0
>
> Related to that is the ability to easily get the documentation programatically from the loaded code with the Code.get_docs/2 function. This allows various tools to access the documentation and present it directly in the code editor or whatever you can imagine.
>
> Michał.
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>

-- 
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang