most ddoc examples not runnable; Edit is buggy; DDOC generates wrong Example tag

[timotheecour]

Is there any short term plan to make examples in ddoc runnable?
right now, the only one that runs is the one on the home page 
dlang.org.

Example: in http://dlang.org/phobos/std_path.html:
the 1st code sample (under baseName)

when you click on run:
/home/c318/c110.d(2): Error: Declaration expected, not 'assert'

when you click on Edit and wrap the code sample in this:
----
import std.path;
void main(){
...
}
----

now it runs fine.

I propose:

A)
the examples should be runnable by default (at least a majority 
of them, in the meantime)

B)
we can do this either by requesting user code to write runnable 
examples (would require a lot of changes in documentation, maybe 
not so good and verbose), or by implicitly wrapping each example 
inside a main function, with proper import declarations (ala rdmd 
--eval, which imports all phobos). That may be overkill and 
produce name clashes (std.file.write,std.stdio.write,..). Maybe 
just import current module implicitly, all else requires the user 
to explicitly import.

C)
to keep examples in sync (I just made a pull request that fixes a 
wrong syntax in std.random), there should be an autotester that 
does just that, at least verifying stuff compiles, if not runs 
without breaking asserts.

D)
will that be obsoleted by unittests appearing in ddoc?

E)
right now Edit button in those examples is buggy:
try clicking on Edit in second example box in baseName's example: 
the code is replaced by something different from example above.

F)
The DDOC generates extraneous "Example:" tag in almost all cases 
(see for example in dirName: you have Examples: ... (ok) and then 
Exampe: (empty)