Tuesday, February 24, 2015

Writing Effective Examples in Elixir docstrings.

I had an email exchange on the elixir-core mailing list recently that I think is worth preserving as a blog post. It shows a great approach to how to write examples for functions with complex output.

We had a meetup this weekend for hacking the docs. The intent was to add examples to the standard library. 

I started looking around in code.ex and the question I run into is the following:

Should examples be functionally accurate or readable? 

Here's what I mean. I was attempting to add an example for 

Code.get_docs. 

This is what I came up with. 

## Examples

      iex> Code.get_docs(Atom, :docs)
      [{{:to_char_list, 1}, 36, :def, [{:atom, [], nil}],
      "Converts an atom to a char list.\\n\\nInlined by the compiler.\\n\\n## Examples\\n\\n    iex> Atom.to_char_list(:\"An atom\")\\n    'An atom'\\n\\n"},
      {{:to_string, 1}, 20, :def, [{:atom, [], nil}],
      "Converts an atom to a string.\\n\\nInlined by the compiler.\\n\\n## Examples\\n\\n    iex> Atom.to_string(:foo)\\n    \"foo\"\\n\\n"}]
      
      iex(1)> Code.get_docs(Atom, :all )
      [docs: [{{:to_char_list, 1}, 36, :def, [{:atom, [], nil}],
      "Converts an atom to a char list.\\n\\\nInlined by the compiler.\\n\\n## Examples\\n\\n    iex> Atom.to_char_list(:\"An atom\")\\n    'An atom'\\n\\n"},
      {{:to_string, 1}, 20, :def, [{:atom, [], nil}],
      "Converts an atom to a string.\\n\\nInlined by the compiler.\\n\\n## Examples\\n\\n    iex> Atom.to_string(:foo)\\n    \"foo\"\\n\\n"}],
      moduledoc: {1,"Convenience functions for working with atoms.\\n\\nSee also `Kernel.is_atom/1`.\\n"}]
 
It's really messy to read and I'm still working on getting the quoting correct for ex_doc. 
Atom is about the simplest standard module available, so picking anything else just 
gets worse. Also it suffers from the problem that it doesn't automatically update when
the docs for Atom update. 

My initial thought was to dynamically create a Sample module and then use Code.get_docs
on that example ( i.e. similar to the test for Code.get_docs ).  

So I guess the question is: 

Should any examples in the documentation exactly match the results from running the code in iex? 

i.e. while the standard lib does not use doctest as far as I know, any examples included should be
doctest aware. Or is it okay to simplify the results for clarity? 

- Booker C. Bense

José Valim 
Feb 23
Should any examples in the documentation exactly match the results from running the code in iex?

Yes. But you can always "cheat"!

# Get the doc for the first function
iex> [fun|_] = Code.get_docs(Atom, :docs) |> Enum.sort()
# Each clause is in the format
iex> {{_function, _arity}, _line, _kind, _signature, text} = fun
# Let's get the first line of the text
iex> String.split(text, "\n") |> Enum.at!(0)
"NOW YOU HAVE A STRING"

So you are showing the whole process without printing it all the way.


This is a really nice way to take very complex dense output and recast it in a simple example that makes the return value of the function much clearer.