On 10/14/10 8:44 CDT, Steven Schveighoffer wrote:
On Thu, 14 Oct 2010 06:53:35 -0400, Gerrit Wichert <gwich...@yahoo.com>
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've asked Walter many times for
/// Example
unittest
{
...
}
such that the code of the unittest will also appear as a documentation
example. It would be a huge improvement in both test coverage and
documentation, but it never made it to the top of the list.
Andrei
