Make doctests from code texts for case/2

[dmitrykleymenov]

No description provided.

[josevalim]

💚 💙 💜 💛 ❤️

[sabiwara]

My only concern here is that the previous version, although not a runnable doctest, felt like a more idiomatic example (log and fallback on a sensible default) vs returning a string.

[dmitrykleymenov]

Shouldn't it be rewritten into something like:

iex> require Logger
iex> file = "no_file.txt"
iex> case File.read(file) do
...>   {:ok, contents} when is_binary(contents) ->
...>     String.split(contents, "\n")
...>   {:error, _reason} ->
...>     Logger.warning "Can't read the #{file} file, assuming empty..."
...>     []  
...> end
[]

?

[sabiwara]

Not all code in docs is or can be evaluated (side effects, complicated setup etc) (see this), and I think it is fine.

Non-doctests code examples aren't prefixed by iex>.
You can see many examples in the File module.

[dmitrykleymenov]

I agree, but doctests instead of plain code texts provide assurance(for reader) of typos and other errors absence. Also doctests don't have implicit parts(as you mentioned: side effects, internal setup and other) and much more clear and easy to understand. In case when we can't avoid side effects(as in File) it's ok, but here, i'm sure, it's possible to find a good(ideomatic) pure functional example of usage, which can be doctested.
In other words, when I read a doctest i'm 100% sure it works, and that helps.

[sabiwara]

I understand the arguments in favor of doctests and I agree they are nice when possible for pure functions.

For conditionals like case/if/cond..., hard-coding the condition to have a runnable doctest might also make the example less realistic and it only demonstrates one branch, but it seems we are not consistent across these.

i'm sure, it's possible to find a good(ideomatic) pure functional example of usage, which can be doctested.

Sounds good! How about some parsing like Date.from_iso8601/1?

[dmitrykleymenov]

Great, i'll do a pr