Documentation

Annotation

How much we comment and what makes quality documentation remains a contentious issue within the programming world. However, we can all agree that documentation is important for ourselves and those working with our codebase.

Elixir treats documentation as a first-class citizen, offering various functions to access and generate documentation for your projects. The Elixir core provides us with many different attributes to annotate a codebase. Let’s look at 3 ways:

• # - For inline documentation.
• @moduledoc - For module-level documentation.
• @doc - For function-level documentation.

Inline Documentation

Probably the simplest way to comment your code is with inline comments. Similar to Ruby or Python, Elixir’s inline comment is denoted with a #, frequently known as a pound, or a hash depending on where you are from in the world.

Take this Elixir Script (greeting.exs):

# Outputs 'Hello, chum.' to the console.
IO.puts("Hello, " <> "chum.")

Elixir, when running this script will ignore everything from # to the end of the line, treating it as throwaway data. It may add no value to the operation or performance of the script, however when it’s not so obvious what is happening a programmer should know from reading your comment. Be mindful not to abuse the single line comment! Littering a codebase could become an unwelcome nightmare for some. It is best used in moderation.

Documenting Modules

The @moduledoc annotator allows for inline documentation at a module level. It typically sits just under the defmodule declaration at the top of a file. The example below shows a one line comment within the @moduledoc decorator.

defmodule Greeter do
  @moduledoc """
  Provides a function `hello/1` to greet a human
  """

  def hello(name) do
    "Hello, " <> name
  end
end

We (or others) can access this module documentation using the h helper function within IEx. However, utilizing the h helper function immediately after creating a module in iex can lead to the following issue:

iex> h Greeter
Greeter was not compiled with docs

Reason: When code is entered into iex, Elixir’s interactive shell compiles it in memory without automatically writing the compiled code to disk. Saving compiled bytecode requires explicit instructions, either by explicitly saving the bytecode or by utilizing Elixir’s file I/O functions to write it to a file.

Consider a scenario where there’s a file named greeter.ex in the current working directory, and an iex session is launched from there:

iex> c("greeter.ex")
[Greeter]

iex> h Greeter
Greeter was not compiled with docs

Encountering the same issue here is expected due to the nature of c("greeter.ex"). This command compiles the file in memory but doesn’t automatically write the bytecode (.beam file) to disk. However, for the h/1 helper to function correctly, the .beam file needs to exist on disk.

To resolve this, it’s essential to instruct c to store the generated bytecode in the current directory. This action enables the h/1 helper to access and display the documentation as intended.

iex> c("greeter.ex", ".")
[Greeter]

iex> h Greeter

                Greeter

Provides a function hello/1 to greet a human

Note: we don’t need to manually compile our files as we did above if we’re working within the context of a mix project. You can use iex -S mix to load the IEx console for the current project if you’re working in a mix project.

Documenting Functions

Just as Elixir gives us the ability for module level annotation, it also enables similar annotations for documenting functions. The @doc annotator allows for inline documentation at a function level. The @doc annotator sits just above the function it is annotating.

defmodule Greeter do
  @moduledoc """
  ...
  """

  @doc """
  Prints a hello message.

  ## Parameters

    - name: String that represents the name of the person.

  ## Examples

      iex> Greeter.hello("Sean")
      "Hello, Sean"

      iex> Greeter.hello("pete")
      "Hello, pete"

  """
  @spec hello(String.t()) :: String.t()
  def hello(name) do
    "Hello, " <> name
  end
end

If we kick into IEx again and use the helper command (h) on the function prepended with the module name, we should see the following:

iex> c("greeter.ex", ".")
[Greeter]

iex> h Greeter.hello

                def hello(name)

  @spec hello(String.t()) :: String.t()

Prints a hello message.

Parameters

  • name: String that represents the name of the person.

Examples

    iex> Greeter.hello("Sean")
    "Hello, Sean"

    iex> Greeter.hello("pete")
    "Hello, pete"

iex>

Notice how you can use markup within our documentation and the terminal will render it? Apart from really being cool and a novel addition to Elixir’s vast ecosystem, it gets much more interesting when we look at ExDoc to generate HTML documentation on the fly.

Note: the @spec annotation is used to statically analyze code. To learn more about it, check out the Specifications and types lesson.

ExDoc

ExDoc is an official Elixir project that can be found on GitHub. It produces HTML (HyperText Markup Language) and online documentation for Elixir projects. First let’s create a Mix project for our application:

$ mix new greet_everyone

* creating README.md
* creating .formatter.exs
* creating .gitignore
* creating mix.exs
* creating lib
* creating lib/greet_everyone.ex
* creating test
* creating test/test_helper.exs
* creating test/greet_everyone_test.exs

Your Mix project was created successfully.
You can use "mix" to compile it, test it, and more:

    cd greet_everyone
    mix test

Run "mix help" for more commands.

$ cd greet_everyone

Now copy and paste the code from the @doc annotator lesson into a file called lib/greeter.ex and make sure everything is still working from the command line. Now that we are working within a Mix project we need to start IEx a little differently using the iex -S mix command sequence:

iex> h Greeter.hello

                def hello(name)

  @spec hello(String.t()) :: String.t()

Prints a hello message.

Parameters

  • name: String that represents the name of the person.

Examples

    iex> Greeter.hello("Sean")
    "Hello, Sean"

    iex> Greeter.hello("pete")
    "Hello, pete"

Installing

Assuming all is well and we’re seeing the output above, we are now ready to set up ExDoc. In the mix.exs file, add the :ex_doc dependency to get started.

  def deps do
    [{:ex_doc, "~> 0.21", only: :dev, runtime: false}]
  end

We specify the only: :dev key-value pair as we don’t want to download and compile the ex_doc dependency in a production environment.

ex_doc will also add another library for us, Earmark.

Earmark is a Markdown parser for the Elixir programming language that ExDoc utilizes to turn our documentation within @moduledoc and @doc to beautiful looking HTML.

It is worth noting at this point that you can change the markup tool to Cmark if you wish, but you will need to do a little more configuration which you can read about here. For this tutorial, we’ll just stick with Earmark.

Generating Documentation

Carrying on, from the command line run the following two commands:

$ mix deps.get # gets ExDoc + Earmark.
$ mix docs # makes the documentation.

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

If everything went to plan, you should see a similar message as to the output message in the above example. Let’s now look inside our Mix project and we should see that there is another directory called doc/. Inside is our generated documentation. If we visit the index page in our browser we should see the following:

We can see that Earmark has rendered our Markdown and ExDoc is now displaying it in a useful format.

We can now deploy this to GitHub, our own website, or more commonly HexDocs.

Best Practice

Documentation should be added within the Best Practices Guidelines of the language. Since Elixir is a fairly young language many standards are still to be discovered as the ecosystem grows. The community, however, tried to establish best practices. To read more about best practices see The Elixir Style Guide.

• Always document a module.

defmodule Greeter do
  @moduledoc """
  This is good documentation.
  """

end

• If you do not intend to document a module, do not leave it blank. Consider annotating the module false, like so:

defmodule Greeter do
  @moduledoc false

end

• When referring to functions within module documentation, use backticks like so:

defmodule Greeter do
  @moduledoc """
  ...

  This module also has a `hello/1` function.
  """

  def hello(name) do
    IO.puts("Hello, " <> name)
  end
end

• Separate any and all code one line under the @moduledoc as so:

defmodule Greeter do
  @moduledoc """
  ...

  This module also has a `hello/1` function.
  """

  alias Goodbye.bye_bye
  # and so on...

  def hello(name) do
    IO.puts("Hello, " <> name)
  end
end

• Use Markdown within docs. It will make it easier to read either via IEx or ExDoc.

defmodule Greeter do
  @moduledoc """
  ...
  """

  @doc """
  Prints a hello message

  ## Parameters

    - name: String that represents the name of the person.

  ## Examples

      iex> Greeter.hello("Sean")
      "Hello, Sean"

      iex> Greeter.hello("pete")
      "Hello, pete"

  """
  @spec hello(String.t()) :: String.t()
  def hello(name) do
    "Hello, " <> name
  end
end

• Try to include some code examples in your documentation. This also allows you to generate automatic tests from the code examples found in a module, function, or macro with ExUnit.DocTest. In order to do that, you need to invoke the doctest/1 macro from your test case and write your examples according to some guidelines as detailed in the official documentation.

Caught a mistake or want to contribute to the lesson? Edit this lesson on GitHub!