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
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.
No comments:
Post a Comment