Postmortem: Template unittests are bad & you shouldn't catch Error

[Mathias LANG]

On Thursday, 22 October 2020 at 16:34:14 UTC, Adam D. Ruppe wrote:
> On Thursday, 22 October 2020 at 16:18:14 UTC, H. S. Teoh wrote:
>> 2) Ddoc's unittests require unittest blocks to be attached to 
>> the symbol they're documenting.
>
> The whole unittest as example thing was a mistake anyway. It 
> doesn't actually work at all (stuff can pass the test without 
> being a usable example due to scope contexts) and encourages 
> ugly, unusable examples because they are run as automatic tests 
> instead of you know, actually being written as examples.
>
> If I was in charge of it, the documented ones would have to be 
> like static, in that they don't depend on *any* context - the 
> compiler treats each block like its own pseudo-module and you 
> must import everything you use again (this guarantees you only 
> use public things and must demo a complete example) - and allow 
> them to be decoupled.
>
> In adrdox, I let you tag them with an ID, then embed by id in 
> the prose to insert the example where you want it.
>
> Maybe ddoc could do that too so you have some freedom to move 
> it around even if you reject the static paragraph.
>
> (or y'all ditch horrible ddoc and come to good docs. the 
> water's fine.)

Two pretty great idea. Do you have a bugzilla entry for them by 
any chance ?
I don't agree with the sentiment that documented unittests are a 
mistake though: they are a step up from documentation examples, 
because you are at least guaranteed they compile and pass in the 
right context. Examples in documentation might not even compile 
from day 1 because of a typo, or fail to compile when a symbol / 
language feature is deprecated or removed.

But making them context-independent is definitely an idea worth 
exploring.