Skip to content

Latest commit

 

History

History
119 lines (79 loc) · 3.33 KB

doctests.livemd

File metadata and controls

119 lines (79 loc) · 3.33 KB

Doctests

Mix.install([
  {:youtube, github: "brooklinjazz/youtube"},
  {:hidden_cell, github: "brooklinjazz/hidden_cell"},
  {:tested_cell, github: "brooklinjazz/tested_cell"},
  {:utils, path: "#{__DIR__}/../utils"}
])

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.

Commit Your Progress

Run the following in your command line from the beta_curriculum folder to track and save your progress in a Git commit.

$ git add .
$ git commit -m "finish doctests section"

Up Next

Previous Next
Games Wordle Typespecs