Docs in the shell 2: Man-Erlang interface

2017-05-23 by Radek Szymczyszyn

Learn more about how Erlang Solutions’ Erlang and Elixir Solutions or sign up to our mailing list to be the first to know about our future blog posts.

It’s been a while since the last update on docsh and over a year since the idea of shell access to Erlang docs originally emerged in my mind. Believe it or not, the project has seen a huge progress, though one might argue that at a pace a tad slower than the speed of light. By the way, if you ask me, it’s “doc-es-age”, not “doc-shhh”.

Let’s recap what the original goals were, whether they’ve shifted, and how we fared realising them.

Require as little fuss as possible to use

If you’re just beginning your Erlang journey, there’s an install script available, which will take care of the default setup in a few seconds. Install Erlang, clone docsh, run install.sh and there you are!

For the veterans: the install script won’t mess up your precious Erlang development environment settings, it’s going to balk at touching your config files, but will provide hints on how you can enable doc access manually.

Provide value to the developer no matter whether they use community or OTP libraries

Once docsh is installed, when you run erl it will greet you with a reminder that docsh is enabled. From this point, the shell is equipped with a new set of helper functions for accessing the documentation of modules and functions, function specs, and type definitions. These helpers will look familiar to those who had a sip of Elixir, but have been adapted to Erlang’s syntax. If in doubt, refer to h(docsh). in the Erlang shell - that is, use docsh to view its own documentation. The README and some examples might also whet your appetite some more if you’re not yet convinced enough to install the tool.

There’s one caveat at the moment, though. The so called Erlang/OTP source bundles (i.e. the .tar.gz archives you can get from erlang.org), you use to install from source, aren’t really exactly the thing they’re supposed to be. The C source code included within is compiled on your machine during installation, but the standard Erlang modules come precompiled on the tarball packager’s machine.

When docsh inspects a module, in some cases it tries to find its source code. Given the source file path is not valid on your machine, documentation extraction will fail. All in all, unless you take extra steps when installing Erlang, currently for the standard OTP modules docsh can only provide function specs, not the inline EDoc documentation one might expect. Despite that, the specs can be more than enough to tell what a function does, and are an invaluable help when determining its parameters’ meaning and order. This EDoc extraction from OTP modules thing is a known issue and will be fixed in the future.

Make docsh documentation compatible with Elixir’s format for IEx to use

This goal was twofold: to make the internal format compatible with Elixir and to enable IEx (Elixir shell) to access Erlang documentation. While the internal format compatibility is shelved for now, the access from the Elixir aspect has progressed somewhat.

However, there are more languages on the BEAM (the Erlang VM) than just Elixir and Erlang. For instance LFE, Efene and Alpaca come to mind. With Alpaca having an open issue on the doc string system they’re designing, there’s some space for research and maybe even for future collaboration.

Back to Elixir, though - there’s a project called Ehelper, whose goals overlap a bit with those of docsh. Ehelper aims to extend the Elixir shell with programmable plugins. Thanks to this architecture, docsh could be an Erlang documentation provider for Ehelper. It might be the way to go, but tinkering directly with Elixir’s .iex.exs might be more straightforward. I have to spend more time on finding the most convenient approach for everyday use. Let’s see how it unfolds.

In the original blog post, I also highlighted some issues which were yet to be solved back then. The first one was documentation format diversity: at least Markdown, AsciiDoc and EDoc are used for documentation in the Erlang community, while the OTP Team also uses non-EDoc XML out-of-source docs for the standard library (the Erlang manpages are generated from it). This is addressed in docsh by defining a docsh_reader behaviour, which implementations can consume different inputs and produce a docsh-internal representation. This internal format is written out by a docsh_writer .

Currently, there are two readers: one for reading the Erlang abstract syntax tree (stored in modules if debug_info option is passed to the compiler), and one for reading EDoc comments from source files. That’s why even if the source files aren’t available the function specs can still be extracted from Erlang modules. Only one writer is available for now - it embeds the documentation into the module .beam file for later recovery.

Whew, that was a long one! Check out how docsh makes your everyday life easier and let me know where it could use some improvements!

Learn more about how Erlang Solutions’ Erlang and Elixir Solutions or sign up to our mailing list to be the first to know about our future blog posts.