Writing Comments and Documentation in Elixir

Oct 19, 2016

Table of contents:

1. Writing Comments
2. Module Documentation
3. Function Documentation
4. Testing your Documentation
5. Generating HTML Documentation
6. Conclusion

An important part of writing code is making it easy to understand for other developers or your future self.

In a perfect world, this is achieved through clear and concise code that shows the intent of the developer. There really is no better documentation than the code itself.

However, comments and documentation are a critically important tool for learning. Newbies can’t be expected to pick up something new from the source code alone, and even experienced developers will spend a lot of their time referencing documentation in order to achieve their goals.

Documentation in Elixir is a first-class citizen, and so there are a couple of tools that make writing and using documentation in Elixir particularly useful.

The standard for documentation is already very high in the Elixir ecosystem, especially in the core Elixir code and standard library, and so in order to become a high quality Elixir developer, writing good quality documentation is something you should learn to get grips with.

In today’s tutorial we will be looking at writing comments and documentation as an Elixir developer.

Writing Comments

The first type of documentation you will likely encounter as an Elixir developer is inline comments:

defmodule Maths do
  def add(left, right) do
    # Add two numbers together
    left + right
  end
end

As you can see from the example above, inline comments use the # to mark the entire line as a comment.

I’m not a huge fan of using inline comments and so I tend to use them sparingly, or more often than not, not at all. In my opinion, inline comments are either pointless, or a sign that you need to simplify your code.

However with that being said, it’s often better to have an inline comment than ambiguous code that is hard to understand.

Module Documentation

In elixir, related functions are grouped together into modules (Working with Functions and Modules in Elixir).

Elixir allows you to add module Documentation that gives a brief overview of the purpose of the module, and perhaps a summary of the functions that it contains:

defmodule Maths do
  @moduledoc """
  A module that implements functions for performing simple
  mathematic calculations
  """

  def add(left, right) do
    # Add two numbers together
    left + right
  end
end

You can access the module documentation from inside of iex by using the h/1 function:

h(Maths)

As you might of guessed, you can also use the h/1 function for accessing the module documentation for any of the modules in Elixir:

h(String)

Function Documentation

Each public function of a module can also have documentation by using the @doc annotation:

defmodule Maths do
  @moduledoc """
  A module that implements functions for performing simple
  mathematic calculations
  """

  @doc """
  Add two numbers together
  """
  def add(left, right) do
    # Add two numbers together
    left + right
  end
end

As with module documentation, you can also use the h/1 function in iex to read the documentation for a function:

h(Maths.add())

Testing your Documentation

One of the most interesting things in the world of Elixir documentation is that you can write examples in your functions documentation.

These examples can then be run as part of your test suite, so you ensure that the examples in your documentation are actually working correctly!

For example, if we were to write the following (incorrect) example in our documentation, and then run the tests, the tests will complain that the wrong value was given.

@doc """
Add two numbers together

Examples

iex> Maths.add(4, 2)
5
"""
def add(left, right) do
  # Add two numbers together
  left + right
end

This is really a great feature of Elixir as examples in documentation quickly go stale if the code is updated but the documentation is neglected.

Generating HTML Documentation

The final interesting thing to look at concerning documentation in Elixir is the ability to generate HTML documentation straight from your code.

If you have ever read through the official Elixir documentation, this is exactly how this documentation is generated!

To generate HTML documentation, first add the following document packages to your Mix project:

defp deps do
  [
    {:earmark, "~> 0.1", only: :dev},
    {:ex_doc, "~> 0.11", only: :dev}
  ]
end

After you have added the dependencies above to your mix.exs file, run the following command in your terminal to pull them into your project:

mix deps.get

Now that we have everything we need, we can generate the documentation with the following command:

mix docs

If everything goes smoothly you should see the following message in your terminal:

Docs successfully generated.
View them at "doc/index.html".

Now open up the doc/index.html file in a browser, you should see your Elixir style generated documentation. If you click into the Maths module documentation you should see the documentation you wrote in your module, including the iex examples!

Conclusion

If I’m being honest, I’m not a huge fan of writing documentation. I much prefer writing clear code that is easy to understand by my colleagues and my future self.

However, writing documentation is something you just have to do.

Elixir makes it really beneficial to write documentation. I love the doc test functionality to ensure examples in documentation are working correctly. I’ve been stung in other languages where documentation has drifted from the implementation because the code has been update but the examples have gone stale.

And I really like how easy it is to generate online HTML documentation for your code without having to duplicate any effort.

If you would like to play around with the code and documentation for this tutorial, take a look at the accompanying git repository.