Needed enhancement for documentable unittest

[Andrej Mitrovic]

On 3/25/13, Jens Mueller <jens.k.mueller at gmx.de> wrote:
> I thought the example (embedded code) is not being moved into unittests
> rather it's copied.

No, that's not how it works. Code in in documented unittests is moved
into Example sections in ddoc output. So the new definition of map
would look like:

<quote>
/**
$(D auto map2(Range)(Range r) if (isInputRange!(Unqual!Range));)

Implements the homonym function (also known as $(D transform)) present
in many languages of functional flavor. The call $(D map!(fun)(range))
returns a range of which elements are obtained by applying $(D fun(x))
left to right for all $(D x) in $(D range). The original ranges are
not changed. Evaluation is done lazily.
*/
template map2(fun...) if (fun.length >= 1)
{
    auto map2(Range)(Range r)
    {

    }
}

///
unittest
{
    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, the
element type of $(D map) is a tuple containing one element for each
function.
*/
unittest
{
    auto arr1 = [ 1, 2, 3, 4 ];
    foreach (e; map!("a + a", "a * a")(arr1))
    {
        writeln(e[0], " ", e[1]);
    }
}

/**
You may alias $(D map) with some function(s) to a symbol and use
it separately:
*/
unittest
{
    alias map!(to!string) stringize;
    assert(equal(stringize([ 1, 2, 3, 4 ]), [ "1", "2", "3", "4" ]));
}
</quote>

This will look similar to how it looks now in the documentation.

My problem is that the actual documentation text in the source file is
now spread out into unittest comments rather than being at a single
place (right next to the function header).

It may or may not be a problem, I'm on the fence about it.