Support our default inspect notation on doctests

[josevalim]

It has already been suggested and noted a couple times that doctests do not support the inspect notation. For example, we can't test this:

iex> Version.parse("2.0.1-alpha1")
#Version.Schema<2.0.1-alpha1>

This is because doctests work on expressions and not inspected values. This means, tests like this would likely pass:

iex> 5 - 3
1 + 2

We have a couple solutions to work around this problem:

1. Stop pretending that doctests is an actual iex and replace iex> by doc> (or something similar).
2. Make doctests actually rely on the inspected values. I don't like this option because it means it becomes space sensitive and you lose flexibility when formatting the docs.
3. Keep as is but support #Version.Schema<2.0.1-alpha1> and such in docs.

The issue with 3 is that it is hard to know if it is a comment or the inspected value. We could add a check that checks if the given expression match %r"\#(\w+\.?)+<" and then do a match on the inspected value but this means we are adding a special case to how doctests. And it still doesn't solve the fact it does not behave as IEx.

It seems to me the ideal would be to mix 1 and 3. Rename it to doc> and add support for #Version.Schema and such.

Ideas?

/cc @meh @alco @ericmj @jwarwick

[JordiPolo]

Thinking about it, it seems that working on expresion is good enough.
if Version.Squema is a record(with a version field), that test can be written like:

iex> Version.parse("2.0.1-alpha1")
Version.Schema[version: "2.0.1-alpha1"]

And let it pattern match.

iex> 5 - 3
1 + 1

Seems valid to me. Something I may want to write like that to clarify where the number comes from for instance.

[josevalim]

@JordiPolo Good point. But then it means we shouldn't call it iex> because that's now the result we would get on IEx. :) So we still would have to go with 1).

[ericmj]

Working only on expression is not enough when we want to express more
complex records such as HashDict.

On Sat, Oct 26, 2013 at 5:41 PM, José Valim [email protected]:

@JordiPolo https://github.com/JordiPolo Good point. But then it means
we shouldn't call it iex> because that's now the result we would get on
IEx. :) So we still would have to go with 1).

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1815#issuecomment-27148810
.

Eric Meadows-Jönsson

[jdashton]

Speaking out of turn here (and ignorance), but perhaps you could enable option #3 by "enhancing" the comment syntax, somewhat as Javadoc does, perhaps with a simple doubled-hash:
##Version.Schema<2.0.1-alpha1>

If it starts with two hashmarks, you know it's inspect notation.

[meh]

I think 3 is enough, doing so would also kind of enforce the idea of inspecting values that way (which is already pervasive in Elixir).

Sincerely I'd also go as far as suggesting adding support for comments limited that way, like Clojure does with #_.

something |> something_else(#<"I was here, but let's try the default parameter">) |> keep_going