Example unittests?

[WebFreak001]

Currently when writing functions you have 2 ways to include 
documentation in them:

1. write a ddoc section called `Examples`, put code between `---` 
or `` ``` `` blocks
2. create `unittest` blocks immediately following the symbol and 
put a ddoc comment onto them (`///`, optionally with text)

While this is great for documenting all the edge cases, it might 
not be so well usable while coding and quickly wanting to see 
short and concise code examples for a function. Additionally such 
examples wouldn't really classify as "unittests", but might still 
be nice to be auto-validated by the unittest feature.

In particular I'm looking at 
https://github.com/dlang-community/DCD/pull/684 which now shows 
all documented unittests as part of the hover / autocomplete 
documentation. It's quite a big chunk of information and less 
might be more while the user doesn't want to look at the full 
documentation.

So I'm asking you what do you think of this issue?

1. Should we get this PR in as-is, effectively letting library 
authors decide if they want to optimize for auto complete 
readability (possibly worsening the documentation quality), but 
always giving the user full information
2. Don't add this feature to DCD, only keep the ddoc string 
examples in (which don't get auto-tested, but could be, if we 
added a dub feature and create all the tooling there)
3. Add explicit example blocks (e.g. `@example unittest { ... }`) 
- this would require a `example` symbol to be defined somewhere 
though, or a special case in the compiler, like with `nogc` and 
`live` (also some kind of standard UDA library might make in 
general, for things like D-Scanner as well)