improving the join function

[Steven Schveighoffer]

On Thu, 14 Oct 2010 06:53:35 -0400, Gerrit Wichert <gwichert at 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