"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?
