Docs in the shell 2: Man-Erlang interface
by Radek Szymczyszyn
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
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
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
which implementations can consume different inputs and produce a
This internal format is written out by a
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!
Go back to the blog