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.