Needed enhancement for documentable unittest

[Timothee Cour]

Examples moved out to unittests:
Cons: doc gets spread out in unittests
Pros: much easier to write those examples, no quoting necessary, code
is syntax highlighted, compilable and ran by unittest suite.
Much better than the hack of embedding examples inside doc
For proof, see how many embedded examples are out of date. Or even compilable.


On Fri, Mar 29, 2013 at 11:46 PM, Andrej Mitrovic
<andrej.mitrovich at gmail.com> wrote:
> 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.