www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Re: Needed enhancement for documentable unittest

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.
Mar 24 2013