Adding examples to the standard lib documentation.

[Booker Bense]

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]

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.

[Booker Bense]

thanks, that's a really helpful approach. 

- Booker C. Bnese

[Rich Morin]

On Monday, February 23, 2015 at 10:22:41 AM UTC-8, José Valim wrote:

...

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

FWIW, I used a similar hack in my examples for Bitwise, eg:

      iex> bnot(2)
      -3
      iex> bnot(2) &&& 3
      1

However, in some of my local code, I punt the whole problem by evading doctest's scrutiny, eg:

      $ mix -s iex

      ...

      IEx> import CFCL

      nil

      ...

[Booker Bense]

More trickiness in documenting code.ex with examples. 

I've got one example that fails at irregular intervals when the doctest tests are run. 

    iex> Code.append_path(".")

    iex> :code.get_path |> List.last |> Kernel.to_string == Path.expand(".")

    true

I'm pretty sure is that this is because this function has a global side effect  and there is some kind of race issue wrt 

other examples that tweak the path. Is there a macro I can put in the file to tell doctest to run these tests one at a time? 

- Booker C. Bense

[José Valim]

Another good example/question Booker!

I would avoid doctesting this particular function as this particular example doesn't show its actual behaviour just that its value was stored somewhere (which requires Erlang API to test).

Unfortunately we can't doctests all functions.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/47dfea7c-9259-4480-b2b3-16eb37a75d8b%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Booker Bense]

On Wednesday, February 25, 2015 at 2:36:14 PM UTC-8, José Valim wrote:

Another good example/question Booker!

I would avoid doctesting this particular function as this particular example doesn't show its actual behaviour just that its value was stored somewhere (which requires Erlang API to test).

Unfortunately we can't doctests all functions.

Is it okay to put in an example w/o the iex prompt? Or just skip it altogether? 

- Booker C. Bense  

[José Valim]

Is it okay to put in an example w/o the iex prompt?

Yes, a non-doctest example still works great.

[Rich Morin]

On Feb 25, 2015, at 14:35, José Valim <jose....@plataformatec.com.br> wrote:
> Unfortunately we can't doctests all functions.

This doctest intentionally left blank.

Seriously, it would be nice to indicate the fact (and rationale) when
no example is given.

-r

--
http://www.cfcl.com/rdm Rich Morin r...@cfcl.com
http://www.cfcl.com/rdm/resume San Bruno, CA, USA +1 650-873-7841

Software system design, development, and documentation