automatic code examples in documentation

[Lutger]

Andrei Alexandrescu wrote:

> 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

for reference: http://d.puremagic.com/issues/show_bug.cgi?id=2630

Tomasz Sowiński raises the point that each unittest should test the 
preceding declaration. I think that's a little inflexible, instead the 
following could work:

- unittests marked with 'ditto' will document the preceding declaration
- unittest not marked with ditto will be put in a hardwired macro like BODY 
is, so that you have control where it gets put in the generated 
documentation.