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 Gerrit
