Needed enhancement for documentable unittest

[Andrej Mitrovic]

On 2/7/13, Andrei Alexandrescu <SeeWebsiteForEmail at erdani.org> wrote:
> I'm very happy that this will be part of the upcoming release:
> https://github.com/D-Programming-Language/dmd/pull/1342 (see also
> http://d.puremagic.com/issues/show_bug.cgi?id=2630) allows defining
> unittests that simultaneously work as documentation. This is a great way
> to simultaneously write meaningful tests and good documentation examples.
>
> If you want to help, feel free to hop on the Phobos documentation and
> convert some of it to use the new feature.

Kenji and I have been working on getting this feature working
properly, and it should be pretty solid by now in DMD-head.

But one case where it might not be a good idea to move the embedded
code into unittests is when you have a big comment section, for
example the one for std.algorithm.map. I think this should be a new
enhancement request. Here's part of the documentation for map:

-- START --

$(D auto map(Range)(Range r) if (isInputRange!(Unqual!Range));)

Implements the homonym function...

Example:
----
int[] arr1 = [ 1, 2, 3, 4 ];
int[] arr2 = [ 5, 6 ];
auto squares = map!(a => a * a)(chain(arr1, arr2));
assert(equal(squares, [ 1, 4, 9, 16, 25, 36 ]));
----

Multiple functions can be passed to $(D map). In that case, ...

Example:

----
auto arr1 = [ 1, 2, 3, 4 ];
foreach (e; map!("a + a", "a * a")(arr1))
{
    writeln(e[0], " ", e[1]);
}
----

-- END --

I think we should be able to introduce a new macro that takes an index
and is only handled by ddoc internally, which is replaced with the
documented unittest. The above would then be rewritten to:

-- START --

$(D auto map(Range)(Range r) if (isInputRange!(Unqual!Range));)

Implements the homonym function...

$(DOC_EXAMPLE 1)

Multiple functions can be passed to $(D map). In that case, ...

$(DOC_EXAMPLE 2)

-- END --

And the two examples themselves would be moved to ddoc'ed unittests. I
think this would be nicer than trying to actually push the function
documentation into the unittests themselves.