Phobos runnable examples - ideas request

[nazriel]

Greetings.

I would like to finish Phobos runnable examples case. But I need 
help in picking one strategy for implementation details.

Current state of things is rather bad.
Apart from the fact that lots of examples are not valid examples 
per se

(first example in std.algorithm:
     ---
     int[] a = ...;
     static bool greater(int a, int b)
     ---
)

lots of examples have got outdated assertions in the unittest 
blocks etc.

Requesting user to edit code first, add main(){} block or fix 
invalid D code and then run example itself is unacceptable.

Snippets at main dlang.org website work well because all examples 
are valid D code which compiles out of box. While phobos examples 
are just taken out of context.

The options I've gathered so far:
1) Make all examples valid D code by hand. Make JavaScript assume 
that all code examples in Phobos documentation should be wrapped 
in void main() {} blocks. Add default set of includes + the 
module we are on. Explicitly mark examples that are full programs 
(ie. std.concurrency ones) and don't append void main() {} blocks 
to them. Code should be already wrapped in main(){} block after 
clicking Edit button. Append all special cases where default 
stdin and stdargs are needed like it is done on main webpage ( 
http://dlang.org/js/run.js and 
http://dlang.org/js/run-main-website.js )

2) Make JavaScript assume that all code examples in Phobos 
documentation should be wrapped in void main() {} blocks. Create 
subpage with wiki-like database where special cases would be 
added and script could fetch data from it.
For example adding default stdin and stdargs arguments and 
special includes.

3) The old macro approach, with wrapping examples in $(D_RUN) 
macro. Probably won't scale now due to "unittest is example" 
change in DDOC generation

4) Let's just forget about phobos having runnable examples. On 
the other hand I think there aren't much Programming Languages in 
which stdlib documentation has runnable examples. For example Go 
website has dedicated subpage with couple Examples that can be 
edited and then compiled but that's all. Nothing more. Something 
like main dlang.org website now.


Sorry for any English related quirks :p
Looking forward for your opinions on this and any better ideas 
you may have!

Regards,
Damian Ziemba