Documentation Support

This page explores some of the documentation support provided by Elixir, Erlang, et al.

Introduction

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

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.

ExDoc (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 (e.g., @doc, @moduledoc, @typedoc), 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 session), etc. 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, mix 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 diagrams. For details, see Resources: Elixir.

Erlang

EDoc (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 (e.g., erlang.org/doc, erlang.org/doc/search, erlang.org/doc/man_index). An independent site (erldocs.com) provides a searchable index.

Projects

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.

Wish List

Here is my personal mixture of ponies (bugs) and unicorns (features). Contributions and corrections welcome!

Archives

Language-based fragmentation is a problem: Hex.pm 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

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!

Unicorns

Computers should document. Humans should explain.

-- me

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 Foo?

  • What messages does each process accept and send?

  • Which functions use Foo.bar and Foo.baz?

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!

Topic revision: r63 - 21 Aug 2016, RichMorin
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CFCL Wiki? Send feedback