improving the join function

[Lars T. Kyllingstad]

On Thu, 14 Oct 2010 09:44:19 -0400, Steven Schveighoffer wrote:

> 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


I agree, this would be awesome.  Keeping doc examples in sync with the 
unittests is a pain.

-Lars