> 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