[erlang-questions] Erlang documentation -- a modest proposal
Wed Sep 28 11:58:31 CEST 2016
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:
> 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.
> erlang-questions mailing list
Author of The Erlanger Playbook,
A book about software development using Erlang
More information about the erlang-questions