This page explores some of the documentation support
provided by Elixir, Erlang, et al.
Document my code? Why do you think they call it "code"?
-- T-shirt by Computer Gear & More
Most programmers realize that documentation can be useful,
even if they don't always enjoy creating it.
So, it isn't surprising that Elixir (with some help from Erlang)
provides strong support for creating documentation.
Elixir treats documentation as a first-class citizen.
This means documentation should be easy to write and easy to read.
-- Elixir - Writing Documentation
Elixir draws a strong distinction between
documentation (which covers code's behavior and interfaces) and
comments (which are used by developers working on the code).
It encourages the inclusion of internal comments,
but has no explicit standards or support for them.
In contrast, Elixir has explicit standards (and convenient, unobtrusive support!)
for documenting modules and public functions.
However, because the goal is to document behavior and interfaces,
there is no support for documentation of private functions.
(Elixir's documentation generator) accepts multi-line strings,
using a combination of Markdown
syntax and conventions
to indicate structure and other distinctions.
The strings are stored as module attributes
making them available during compilation and execution.
Tooling is provided to run embedded tests,
make formatted versions of the strings readable online
(e.g., in a web browser or an IEx
Most of the Elixir ecosystem is documented in this manner;
it is unusual to find an Elixir module in hex.pm
that lacks formal documentation in hexdocs.pm
In Elixir 1.3,
provides the capability to generate various diagrams:
mix apps.tree shows the project's applications.
mix deps.tree shows all application dependencies.
mix xref ... shows all module cross-references.
The resulting diagrams are normally displayed in text form,
but they can also be used to generate DOT
For details, see Resources: Elixir
(Erlang's program documentation generator) is similar to ExDoc,
but it uses HTML
syntax, rather than Markdown.
Erlang also supplies tooling for profiling concurrency and visualizing processes.
For details, see Resources: Erlang
Machine-generated documentation for Erlang modules is available from assorted sites.
The main Erlang site (erlang.org
) provides multiple versions
An independent site (erldocs.com
) provides a searchable index.
I don't know of any project-specific tooling for documentation,
but it seems likely that this will emerge,
as developers recognize and address pain points in Phoenix, Nerves, etc.
In the meanwhile, Phoenix is familiarizing lots of Elixir developers
with existing Elixir and Erlang tooling.
For details, see Resources: Phoenix
Here is my personal mixture of ponies (bugs) and unicorns (features).
Contributions and corrections welcome!
Language-based fragmentation is a problem:
can manage any BEAM-related package,
but many Erlang packages are not represented there (yet :-).
Also, most imported Erlang packages
don't have online documentation at the function or module level.
Meanwhile, the official Erlang documentation could use some love:
- There are no overview / index pages for the Application Groups.
Observer is a useful tool for visualization of process graphs,
but there's plenty room for improvement.
For starters, it should be possible
to filter out, select, or summarize sets of processes,
select which information to display in what manner, etc.
If I have zillions of (say) poolboy processes, just tell me about it once!
Computers should document. Humans should explain.
Put another way, we should use computers to harvest information
and present it in organized, useful formats.
Humans are then left with the (much smaller, but more subtle)
task of explaining design goals and approaches
(e.g., algorithm and data structure choices).
I'd like to see more mechanization and modeling
in the areas of application design, package management, etc.
There are many things that machines could document for us
that are a nuisance to find out manually, e.g.:
- What is the call graph for a given process?
- What is the dependency tree for module
- What messages does each process accept and send?
- Which functions use
Phoenix (supported by a graph database such as Neo4j)
could be used to create a front end to Hex.
This could provide integrated system documentation for published libraries,
as well as unpublished (or even private) development projects.
This wiki page is maintained by Rich Morin
an independent consultant specializing in software design, development, and documentation.
Please feel free to email
comments, inquiries, suggestions, etc!