automatic code examples in documentation

[Andrei Alexandrescu]

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