Doctests

Mix.install([
  {:jason, "~> 1.4"},
  {:kino, "~> 0.8.0", override: true},
  {:youtube, github: "brooklinjazz/youtube"},
  {:hidden_cell, github: "brooklinjazz/hidden_cell"}
])

Navigation

Return Home Report An Issue

Setup

Ensure you type the ea keyboard shortcut to evaluate all Elixir cells before starting. Alternatively you can evaluate the Elixir cells as you read.

Doctests

We use the @moduledoc and @doc module attributes to document our code in a mix project. By documenting our project, we explain to other developers the purpose of our code.

@moduledoc contains documentation for the entire module, and @doc documents the function below it.

When we created the Math mix project, it used the @doc and @moduledoc module attribute to document the main math.ex module.

defmodule Math do
  @moduledoc """
  Documentation for `Math`.
  """

  @doc """
  Hello world.

  ## Examples

      iex> Math.hello()
      :world

  """
  def hello do
    :world
  end
end

Notice the Examples section, which simulates an IEx shell.Any line with iex> is a Doctest. Doctests are run by the corresponding test file math_test.exs using the doctest/2 macro.

ExUnit.start(auto_run: false)

defmodule MathTest do
  use ExUnit.Case
  doctest Math
end

ExUnit.run()

Doctests are generally not as comprehensive as typical testing and are not a full replacement. However, they can be a great way to test the input and output of your code and ensure the documentation remains up to date.

Generally, Doctests go in an Examples section. You can write multiple Doctests like so.

  @doc """
  add data types.

  ## Examples

      iex> Math.add(1, 1)
      2

      iex> Math.add(2.1, 2.1)
      4.2
  """

Your Turn

Previously you converted a Math module into a mix project in the ExUnit with Mix section.

Add doctests to the Math module in the math.ex file for both the add/2 and subtract/2 function. Include an example for each data type (integers, floats, strings, lists, maps, keyword lists).

Further Reading

Consider the following resource(s) to deepen your understanding of the topic.

• ElixirSchools: Documentation
• elixir-lang: doctests

Mark As Completed

file_name = Path.basename(Regex.replace(~r/#.+/, __ENV__.file, ""), ".livemd")

save_name =
  case Path.basename(__DIR__) do
    "reading" -> "doctests_reading"
    "exercises" -> "doctests_exercise"
  end

progress_path = __DIR__ <> "/../progress.json"
existing_progress = File.read!(progress_path) |> Jason.decode!()

default = Map.get(existing_progress, save_name, false)

form =
  Kino.Control.form(
    [
      completed: input = Kino.Input.checkbox("Mark As Completed", default: default)
    ],
    report_changes: true
  )

Task.async(fn ->
  for %{data: %{completed: completed}} <- Kino.Control.stream(form) do
    File.write!(
      progress_path,
      Jason.encode!(Map.put(existing_progress, save_name, completed), pretty: true)
    )
  end
end)

form

Commit Your Progress

Run the following in your command line from the curriculum folder to track and save your progress in a Git commit. Ensure that you do not already have undesired or unrelated changes by running git status or by checking the source control tab in Visual Studio Code.

$ git checkout -b doctests-reading
$ git add .
$ git commit -m "finish doctests reading"
$ git push origin doctests-reading

Create a pull request from your doctests-reading branch to your solutions branch. Please do not create a pull request to the DockYard Academy repository as this will spam our PR tracker.

DockYard Academy Students Only:

Notify your teacher by including @BrooklinJazz in your PR description to get feedback. You (or your teacher) may merge your PR into your solutions branch after review.

If you are interested in joining the next academy cohort, sign up here to receive more news when it is available.

Up Next