On 1/24/11 3:12 PM, Nick Sabalausky wrote:
"Andrei Alexandrescu"<seewebsiteforem...@erdani.org> wrote in message
news:ihkpin$194m$1...@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
