improving the join function

[Jonathan M Davis]

On Thursday, October 14, 2010 07:53:24 Andrei Alexandrescu wrote:
> 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

It would certainly be an improvement to have somethnig like. In the datetime 
code that I've been working on, I've specifically been putting the examples for a 
function in the unittest block for that function, but then you have to remember 
to put it there and keep them in sync. It would be far less error prone if there 
was a way to automate create examples from unit tests or to create unit tests 
from examples.

- Jonathan M Davis