On 03/28/2013 07:46 AM, Timothee Cour wrote:
I think it's too fragile to require examples inside docs to be
runnable. A better way would be to expose those examples in the code
(ie outside of comments). That way, they'll be guaranteed to have
correct syntax, be properly syntax highlighted, and stay in sync with
code.
here's a simple possibility:
----
/**
Here's a comment before
*/
version(ddocs_example) @runnable unittest{
assert (rootName("foo") is null);
assert (rootName("/foo") == "/");
}
version(ddocs_example) @notrunnable unittest{
//do something not meant to be runnable here
assert (rootName("/foo") == "/");
}
/**
Here's a comment after
*/
----
This way, DDOC can easily extract version(ddocs_example) unittest
blocks and present them as runnable examples (for the ones marked with
@runnable). dmd's unittesting would run unittest on those.
This sounds good but won't play good with Phobos developers.
Wraping examples in DDOC macros in the past was already very
controversial for them.
--
Best regards
Damian Ziemba
