automatic code examples in documentation

[Lutger]

Tomek Sowiński wrote:

> Lutger napisał:
> 
>> 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
> 
> Well, a unittest making a trial run of the preceding declaration is a
> convention, natural and widely adopted. That well-trodden path deserves
> to be acknowledged by the doc generator.

That's why I suggested ditto. Any comments can be put as regular code 
comments inside the unittest itself, that will be marked up nicely by ddoc.
 
> Good thing about this idea is that *nothing* changes, no extra gimmicks
> around unittest blocks, the code's natural flow is intact.
> 
>> - 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.
> 
> Hm.. would the hardwired macro name be same for all unittests? If so, the
> notion of implicit ownership by the preceding declaration is necessary so
> that the names wouldn't mix up.
>

Not necessarily. It could just be a container.

With this macro:

DDOC_UNITTEST_MEMBERS = <h2>unittests</h2> $0

/** one plus one*/
unittest { assert(1+1==2); }

/** one minus one */
unittest { assert(1-1==0); }

the above could expand to something like: 

<h2>unittests</h2>
$(DDOC_SUMMARY one plus one)
$(D_CODE unittest { assert(1+1==2); } )
$(DDOC_SUMMARY one minus one)
$(D_CODE unittest { assert(1-1==0); } )