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

[Andrei Alexandrescu]

On 1/24/11 3:12 PM, Nick Sabalausky wrote:
> "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?

Then there better are two examples, one focused on foo and the other on 
bar. Anyway, I don't see the need for such a feature. All I want is to 
have certain unittests appear in the generated documentation.

Andrei