We should support regular comments (a-I). We should not support (a-II) and (a-III) because they are not valid in IEx.
import_iex_helpers sounds like an interesting idea. Is there any helper we would use besides flush()? *José Valim* www.plataformatec.com.br Skype: jv.ptec Founder and Director of R&D On Mon, May 8, 2017 at 4:59 PM, eksperimental <[email protected]> wrote: > I have been working on a few improvements for doctests. > Everything that I'm proposing here has already been implemented. > The proposals started because some modules in Elixir are not being tested > with doctests, and this > is because there are certain limitation in doctest. These improvements aim > to eliminate those. > > My proposal consist of two main points: > > 1) Streamline Doctests with regular examples. > Currently some examples need to be expressed in regular code, not in IEx > examples, because some > features are not supported. > > -- a) Include comments in doctest syntax. > We should allow full-line comments in code (currently only comments > after evaluated expressions > are allowed). My proposal is to have three different kind of comments. > > ---- I) Regular comments, such as: > # this is a regular comment > iex> true > true > > ---- II) Return value comments. > These are useful when we will not get the same value everytime the > function is run. > > iex> spawn(fn -> true end) > #=> PID<0.97.0> > > ---- III) Print comments. > Currently it is not clear when a value is returned or printed on > screen (stdout/stderr), so my > proposal is to create a new convention for this. My suggestion is to > use "#>> ", but it could > be anything. > > iex> IO.puts "Elixir" > #>> Elixir > :ok > > 2) Mimic IEx by allowing user to import IEx.Helpers, which are > automatically imported when IEx is > loaded. > I came across this when I was trying to run doctests in the Port module. > In the examples the > flush/0 function is used which is imported from IEx.Helpers. Currently it > is impossible simulate a > doctest if the whole IEx environment is required, without explicitly > importing IEx.Helpers. > So my proposal is to add an option :import_iex_helpers, which works the > same way as :import > option, taking :true, :false, :only, and :except values (default value is > :false). > > > doctest ModuleToDocTest, import_iex_helpers: true > > or > doctest ModuleToDocTest, import_iex_helpers: [only: [flush: 0]] > > > this way the first example in the Port module could be doctested as: > > iex> port = Port.open({:spawn, "cat"}, [:binary]) > #=> #Port<0.1444> > iex> send port, {self(), {:command, "hello"}} > #=> {#PID<0.80.0>, {:command, "hello"}} > iex> send port, {self(), {:command, "world"}} > #=> {#PID<0.80.0>, {:command, "world"}} > iex> flush() > #>> {#Port<0.1444>, {:data, "hello"}} > #>> {#Port<0.1444>, {:data, "world"}} > :ok > iex> send port, {self(), :close} > #=> {#PID<0.80.0>, :close} > iex> flush() > #>> {#Port<0.1444>, :closed} > :ok > > > The implemented and tested code can be found here: > https://github.com/eksperimental/elixir/tree/doctest_improvements3 > > Thank you for reading and looking forward for your feedback. > > -- > 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 [email protected]. > To view this discussion on the web visit https://groups.google.com/d/ > msgid/elixir-lang-core/20170508215910.65ffd36a. > eksperimental%40autistici.org. > For more options, visit https://groups.google.com/d/optout. > -- 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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4JYOAgK0iiYg3%2B_iKr%3DxXMP5VtYFfVqnhyH48jhmqH3Qg%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
