• Andrej Mitrovic (40/47) Mar 24 2013 Kenji and I have been working on getting this feature working

Andrej Mitrovic <andrej.mitrovich gmail.com> writes:

On 2/7/13, Andrei Alexandrescu <SeeWebsiteForEmail 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.