improving the join function

[Steven Schveighoffer]

On Wed, 13 Oct 2010 16:07:46 -0400, Andrei Alexandrescu  
<SeeWebsiteForEmail at erdani.org> wrote:

>> It's not a problem with phobos, it's a problem with documentation. There
>> is a fundamental issue with documenting complex templates which makes
>> function signatures very difficult to understand. The doc generator can
>> and should simplify things, and I think at some point we should address
>> this. In other words, it should be transformed into a form that's easy
>> to see that it's the same as string[] join(string[][], string[]).
>
> 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.

Even though I consider myself a reasonable parser of function templates,  
sometimes in std.algorithm, I'll stare at a function signature for about  
10 minutes trying to figure out whether I can do what I want, give up and  
finally just try to compile it.

I think what might help is spelling out the constraints somehow and  
especially explaining how the alias parameters work.  They are some sort  
of black magic I don't always understand :)

-Steve