On Thu, 14 Oct 2010 09:44:19 -0400, Steven Schveighoffer wrote: > On Thu, 14 Oct 2010 06:53:35 -0400, Gerrit Wichert <[email protected]> > wrote: > >> Am 13.10.2010 22:07, schrieb Andrei Alexandrescu: >>> >>> Good point. On the other hand, an overly simplified documentation >>> might hinder a good deal of legit uses for advanced users. I wonder >>> how to please everyone. >>> >> I think the best way to explain the usage of a feature are *working* >> code-examples. >> Maybe it's possible to have a special unit-test block named such as >> 'example'. >> The compiler can completely ignore such sections or just syntax check >> them, or ... . >> >> For doc generation they are just taken as they are and put into (or >> linked to) the documentation. >> >> It may be even possible for the doc generator to compile and run these >> samples, so they become some kind of unit test and their possible >> output can be part of the documentation. >> >> Just an idea that comes to my mind > > I really *really* like this idea. Documentation examples are almost as > important as unit tests. Can you start a new thread on this? > > -Steve
I agree, this would be awesome. Keeping doc examples in sync with the unittests is a pain. -Lars
