improving the join function

[Andrei Alexandrescu]

On 10/14/10 8:44 CDT, 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've asked Walter many times for

/// Example
unittest
{
     ...
}

such that the code of the unittest will also appear as a documentation 
example. It would be a huge improvement in both test coverage and 
documentation, but it never made it to the top of the list.


Andrei