ExUnit doctest support for fenced codeblocks

[Chris Keele]

Hey all,

I'm trying to get a project into 80 character lines. Most of the credo violations are long ExUnit doctest lines.

I notice that IO.Ansi.Docs and ExDoc both have support for fenced code blocks, which I prefer in Markdown and would dedent my problem lines sufficiently. However, when I try to run doctests with them, I get:

Doctest did not compile, got: (SyntaxError) lib/library.ex:14: unexpected token: "`" (column 1, codepoint U+0060)

     code: 4

           ```

     stacktrace:

       lib/library.ex:13: Library (module)

Is this omission intentional, or a feature request I could hack on?

[José Valim]

The omission is somewhat intentional as nobody had a strong use case for it. Specially given not using fenced blocks is more readable for those reading the documentation inline.

Also, can I take the opportunity to do a small rant on the 80 spaces limit? It is quite antiquated as a default. Sure, if you prefer it, then fine, but I would not pick it as a default value. IIRC is a limit that comes from punch cards.

Some still defend it based on typograph but those usually recommend 66CPL as best and a maximum of 75. On the other hand, there is a study (a bit old at this point) that measured faster reading times for eletronic mediums with 95CPL: https://www.researchgate.net/publication/253615156_The_Effects_of_Line_Length_on_Reading_Online_News

The paper also shows a strong preference for 35CPL!

If someone is aware of more recent studies or studies specific for programming purposes, please let me know.

I personally prefer 95/100, as Elixir leads to horizontal code with pattern matching, well-named variables, multiple arguments, etc. But it is a personal preference. I wouldn't dare to argue it is an ideal value. :)

--
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-core+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/9560079b-c0e6-4007-9d10-3850a9aa6316%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

[Michał Muskała]

While I agree the original reasons for 80 char limit is rather antiquated, there are still valid reasons today. I tend to keep the 80 chars limit, simply because it allows me to open two files side-by-side without wrapping. That said, I'm don't feel extremely strong about this and even break that rule often myself.

Michał.

> On 30 Oct 2016, at 11:40, José Valim <jose....@plataformatec.com.br> wrote:
>
> The omission is somewhat intentional as nobody had a strong use case for it. Specially given not using fenced blocks is more readable for those reading the documentation inline.
>
> Also, can I take the opportunity to do a small rant on the 80 spaces limit? It is quite antiquated as a default. Sure, if you prefer it, then fine, but I would not pick it as a default value. IIRC is a limit that comes from punch cards.
>
> Some still defend it based on typograph but those usually recommend 66CPL as best and a maximum of 75. On the other hand, there is a study (a bit old at this point) that measured faster reading times for eletronic mediums with 95CPL: https://www.researchgate.net/publication/253615156_The_Effects_of_Line_Length_on_Reading_Online_News
>
> The paper also shows a strong preference for 35CPL!
>
> If someone is aware of more recent studies or studies specific for programming purposes, please let me know.
>
> I personally prefer 95/100, as Elixir leads to horizontal code with pattern matching, well-named variables, multiple arguments, etc. But it is a personal preference. I wouldn't dare to argue it is an ideal value. :)
>
> On Sunday, October 30, 2016, Chris Keele <d...@chriskeele.com> wrote:
> Hey all,
>
> I'm trying to get a project into 80 character lines. Most of the credo violations are long ExUnit doctest lines.
>
> I notice that IO.Ansi.Docs and ExDoc both have support for fenced code blocks, which I prefer in Markdown and would dedent my problem lines sufficiently. However, when I try to run doctests with them, I get:
>
> Doctest did not compile, got: (SyntaxError) lib/library.ex:14: unexpected token: "`" (column 1, codepoint U+0060)
> code: 4
> ```
> stacktrace:
> lib/library.ex:13: Library (module)
>
> Is this omission intentional, or a feature request I could hack on?
>
> --
> 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/9560079b-c0e6-4007-9d10-3850a9aa6316%40googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
>
> --
>
>
> José Valim
> www.plataformatec.com.br
> Skype: jv.ptec
> Founder and Director of R&D
>
>

> --
> 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/CAGnRm4%2B4pMH25DMr_tKL0_SrFGVjnuhP%3DoBe-3Tf7pY4%3DvMFvA%40mail.gmail.com.

[Chris Keele]

> not using fenced blocks is more readable for those reading the documentation inline

This is a good point. In other markdown I've experimented with indenting the block once as a decent compromise between (personal preference in) writability and readability.

> Also, can I take the opportunity to do a small rant on the 80 spaces limit?

👏

My motives were more to figure out credo, and get the noise down to see more meaningful complaints. I've figured out how to customize and filter it now, so I'm satisfied with a wider margin.

> The omission is somewhat intentional

It still does feel... incongruent to me that you can author docs the way you want, publish them with ExDoc, and have a build fail because ExUnit doesn't care for fenced code blocks.

Running doctests should take backseat to writing good docs. I feel like ExUnit should support the full range of ExDoc code blocks, aesthetics aside. If ExDoc didn't support them, I'd feel differently.

> as nobody has a strong usecase for it

I'm lukewarmer on this than I was, after some thought, but I'd probably use it in moduledocs and the consistency angle seems important to me.

[José Valim]

Alright, I am convinced. :) Please send a PR if you would like to see this feature in doctests.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

--
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-core+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/70EE4DDB-1E87-4236-952A-795B9B5E12DF%40chriskeele.com.

[OvermindDL1]

/me coughs:

        {Credo.Check.Readability.MaxLineLength, priority: :low, max_length: 120},

On a side note, I use fence blocks in my doctests without issue?  Just have to have a blank line before/after the code itself:

https://github.com/OvermindDL1/permission_ex/blob/master/lib/permission_ex.ex#L78-L86

On Sunday, October 30, 2016 at 2:58:19 PM UTC-6, José Valim wrote:

Alright, I am convinced. :) Please send a PR if you would like to see this feature in doctests.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

On Sun, Oct 30, 2016 at 8:21 PM, Chris Keele <d...@chriskeele.com> wrote:

> not using fenced blocks is more readable for those reading the documentation inline

This is a good point. In other markdown I've experimented with indenting the block once as a decent compromise between (personal preference in) writability and readability.

> Also, can I take the opportunity to do a small rant on the 80 spaces limit?

👏

My motives were more to figure out credo, and get the noise down to see more meaningful complaints. I've figured out how to customize and filter it now, so I'm satisfied with a wider margin.

> The omission is somewhat intentional

It still does feel... incongruent to me that you can author docs the way you want, publish them with ExDoc, and have a build fail because ExUnit doesn't care for fenced code blocks.

Running doctests should take backseat to writing good docs. I feel like ExUnit should support the full range of ExDoc code blocks, aesthetics aside. If ExDoc didn't support them, I'd feel differently.

> as nobody has a strong usecase for it

I'm lukewarmer on this than I was, after some thought, but I'd probably use it in moduledocs and the consistency angle seems important to me.

--
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.

[Chris Keele]

On Monday, October 31, 2016 at 8:39:31 AM UTC-7, OvermindDL1 wrote:

/me coughs:

        {Credo.Check.Readability.MaxLineLength, priority: :low, max_length: 120},

 

On Sun, Oct 30, 2016 at 8:21 PM, Chris Keele <d...@chriskeele.com> wrote:

I've figured out how to customize and filter it now, so I'm satisfied with a wider margin.

One cool thing I never realized about credo is that you can reapply checks, so I've set it up for now as:

{Credo.Check.Readability.MaxLineLength, priority: :low,  max_length: 90},

{Credo.Check.Readability.MaxLineLength, priority: :high, max_length: 120},

On a side note, I use fence blocks in my doctests without issue?  Just have to have a blank line before/after the code itself.

As it turns out, the issue I was experiencing was that you have to have a blank line in-between the last example and the fence closing, because without it ExUnit interprets the ``` as part of the tests.

You can see in my PR that by making ExUnit aware of fences as test terminators, it allows tighter whitespace around tests, and correctly fails if there are actual issues with the last test itself rather than the lack of a newline.

More importantly, it gives ExUnit and ExDoc feature parity, and additionally raises compile errors on improperly formatted fenced code blocks that would violate the CommonMark spec and cause issues within ExDoc output.