Showing unittest in documentation (Was Re: std.unittests[updated] for review)

[Jonathan M Davis]

On Monday, January 24, 2011 13:35:22 Andrei Alexandrescu wrote:
> On 1/24/11 3:16 PM, Nick Sabalausky wrote:
> > "Andrej Mitrovic"<andrej.mitrovich at gmail.com>  wrote in message
> > news:mailman.910.1295903266.4748.digitalmars-d at puremagic.com...
> > 
> >> It's often the case that you want documentation examples to be short,
> >> but also correct. But you still want to write complex unittests that
> >> you don't want to put in the documentation. Sounds like a perfect
> >> candidate for named unittests:
> >> 
> >> unittest(ddoc)
> >> {
> >> 
> >>    // outputted in documentation
> >> 
> >> }
> >> 
> >> Here "ddoc" would be a predefined identifier, kind of like X86 is for
> >> version() statements.
> >> 
> >> unittest // our own complex unittest that we don't want to output in
> >> the documentation
> >> {
> >> 
> >>     // ...
> >> 
> >> }
> > 
> > That also provides a good solution for unittests that belong in the
> > examples of more than one item:
> > 
> > unittest(foo, bar)
> > {
> > 
> >    // Use both foo and bar
> >    // outputted in documentation
> > 
> > }
> 
> Why make everything complicated? The simplest feature request becomes a
> syntactic and semantic clusterfrak.

I'm _very_ interested in having name unit tests, but I see no reason to conflate 
named unit tests and ddoc examples. I think that that would very quickly make 
named unit tests far less useful than they would be otherwise - especially if 
you go so far as to try and make the unittest block name have any connection to 
the name of the function that the block is supposed to be the example fore.

Simply doing something like /++ Ditto +/ only now it's /++ Examples +/ or /++ 
Example +/ seems far better to me. There's no need to complicate things here or 
conflate to separate concepts.

- Jonathan M Davis