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

[Adam D. Ruppe]

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