Я люблю doctest. Строки iex> внутри @doc, которые реально выполняются через doctest Counter, не дают примерам врать, а для чистого конвейера преобразований это почти идеальная документация.
Но для всего, что общается с другим процессом, они тихо вводят в заблуждение. Пример показывает, что Counter.bump(pid) возвращает {:ok, 1}. Он не может показать, как вызов сдаётся после стандартных 5000 миллисекунд, как из-за этого завершается вызывающий процесс или как сервер всё равно доделывает работу, когда её уже никто не ждёт. Читатель узнаёт форму успешного значения и ничего о сбое, к которому документация должна была его подготовить.
Поэтому я разделяю. Doctest для преобразований данных, где вход полностью определяет выход. Для всего, что уходит в другой процесс, текст и настоящий тест, где прямо сказано, что GenServer.call/3 при тайм-ауте завершает вызывающего, а работа на другой стороне всё ещё может произойти.
Получается длиннее. Зато именно это людям и нужно, когда узел тормозит.
