# Doctests

## Introduction

Many languages use *docstrings* to include code-specific documentation alongside the code it relates to. Elixir does the same, and the docstring format used by elixir is markdown-derived. This is what goes into the documentation on Hexdocs.

One interesting segment of the per-function docstrings is the inclusion of concrete examples of the use. Evaluating a module definition involves treating the examples as simple test cases and checking them. Any failing examples will produce a warning, and – in Livebook – the results get highlighted as seen in the example below. This provides a guarantee – when no warnings are emitted – of the correctness of the examples.

This is sometimes referred to as *doctests* and can be seen as a form of non-exhaustive unit tests. Elixir does, however, in ExUnit have a fully featured unit testing framework.

## Example

A trivial module with five doctests (one of which is failing):

```
defmodule Math do
@doc """
Returns sum of the furst and the second arguments.
## Examples:
iex> Math.add(1, 2)
3
iex> Math.add(1, -1)
0
iex> Math.add(-1, 1)
1
"""
def add(a, b) do
a + b
end
@doc """
Returns the first argument divided by the second.
## Examples:
iex> Math.div(1, 10)
0.1
iex> Math.div(1, 0)
** (ArithmeticError) bad argument in arithmetic expression
"""
def div(a, b) do
a / b
end
end
```

We can now use the definitions:

`Math.add(1, 1)`

**Note:** If you have evaluating the code cell containing the definition of the `Math`

module and hover your mouse over the “add” text in the above code cell you should see the documentation pop up.