On 10/15/2010 10:18 AM, Gerrit Wichert wrote:
This is a post i made deep in the 'improving the join function' thread.
Steven asked me to open a new thread on it, so here it comes.
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
This was the original post, now some more explanation:
How can the syntax look like ?
... library code
@documentation( code) {
//hello world example code
import std.stdio;
void main() {
writeln( "Hello, world!");
}
}
more library code ...
[snip]
So what do you think?
I'm happy with a much more modest change that doesn't add anything to
the syntax. Simply prefixing a unittest with a documentation comment
makes it an example:
/**
The example below illustrates how D gets a basic arithmetic operation
totally right.
*/
unittest
{
assert(1 + 1 == 2);
}
The documentation generator simply plops the comment and then formats
the code as an example code.
Andrei
