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
