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

[Nick Sabalausky]

"Andrei Alexandrescu" <SeeWebsiteForEmail at erdani.org> wrote in message 
news:ihkpin$194m$1 at digitalmars.com...
> On 1/24/11 2:37 PM, Steven Schveighoffer wrote:
>> The second one could be pretty annoying. Consider cases where several
>> functions interact (I've seen this many times on Microsoft's
>> Documentation), and it makes sense to make one example that covers all
>> of them. Having them 'testable' means creating several identical unit
>> tests.
>>
>> One way to easily fix this is to allow an additional parameter to the
>> comment:
>>
>> /**
>> Example(Foo.foo(int), Foo.bar(int)):
>> */
>> unittest
>> {
>> auto foo = new Foo;
>> foo.foo(5);
>> foo.bar(6);
>> assert(foo.toString() == "bazunga!");
>> }
>>
>> The above means, copy the example to both Foo.foo(int) and Foo.bar(int)
>
> Why would I force the reader to read the same example twice? And why would 
> I run the same unittest twice?
>

Documentation is a reference, not a novel. If someone looked up the 
documentation for "bar", why make them jump over to "foo" (and make sure 
they know to do so) to see bar's examples?