I love doctests. iex> lines inside @doc that actually run under doctest Counter keep examples honest, and for a pure pipeline of transformations they're close to perfect documentation.
For anything that talks to another process they quietly mislead. The example shows Counter.bump(pid) returning {:ok, 1}. It can't show the call giving up after the default 5000 milliseconds, the caller exiting because of it, or the server finishing the work anyway after nobody is waiting. A reader learns the shape of the success value and nothing about the failure the docs were supposed to prepare them for.
So I split it. Doctests for data transformations, where the input fully determines the output. For anything that crosses a process, prose plus a real test, saying plainly that GenServer.call/3 exits the caller on timeout and that the work may still happen on the other side.
It's longer. It's also the part people actually need when a node is slow.
