type conversions

[Jonathan M Davis]

> Can the documentation of std.conv be fixed?
> 
> http://dlang.org/phobos/std_conv.html#to
> 
> I mean, all the toImpl methods are documented, but in "to" it clearly
> says "Client code normally calls to!TargetType(value) (and not some
> variant of toImpl." I think all the documentation should be in "to". Now
> it sounds like you know what "to" does... but people read documentation
> because they don't know what it does.

The comment on to could obviously be changed, but it wouldn't be all that fun 
to try and not have toImpl in the documentation. You'd have to do something 
like

version(StdDdoc)
{
 /++
 ddoc comment
 +/
 T to(T, S)(S value)
 if(...)
 {assert(0);}
}
else
{
 T toImpl(T, S)(S Value)
 if(...)
 {...}
}

for every toImpl, which would create undesirable code duplication on top of 
being ugly. You can certainly make the changes and create a pull request for 
them if you want to though. Another approach would simply be to put better 
examples in the documentation.

The weird thing is that there's a huge comment with a variety of examples near 
the top of the file that looks an awful lot like it's intended to be the ddoc 
comment for the module, but it's not actually at the top of the module, nor is 
it on any symbol (and it specifically has a space after its first asterisk so 
that it's not a ddoc comment). It's also, right above to, so maybe it was 
intended to be on to at one point. Either way, it's a bit weird.

- Jonathan M Davis