adrdox vs markdown vs ddoc

[Adam D. Ruppe]

On Thursday, 1 February 2018 at 19:21:52 UTC, H. S. Teoh wrote:
> As far as nested comments are concerned, I'm a firm believer in 
> ddoc'd unittests, so I hardly ever bother with inline code 
> examples, much less ones that need comments, and pretty much 
> never ones that need block comments.

I use the documented unittests too, but they do have some pretty 
big limits: it is hard to embed them around explanatory text and 
actually using them as tests has a few limits:

* the unittest is not fully isolated, but users will copy/paste 
them into separate code. It may pass the test because of, for 
example, an import outside the test, but then fail to compile for 
the end user.

* automated tests are designed for automation and resiliancy, but 
good examples are designed for interactivity and tinkering by the 
user. They are almost opposite in purpose! (even the above goes 
in - a unittest tests a unit... a good example shows how to put 
the pieces together)

* unittests with a main function are a little wonky, but you can 
make it work.


I still kinda like it... but I think it is actually overrated.