On Wednesday, 30 December 2015 at 04:03:42 UTC, Andrei
Alexandrescu wrote:
On 12/29/2015 09:09 PM, Adam D. Ruppe wrote:
Putting one item per page is far more important than I even
realized
before getting into this.
We already have that:
https://dlang.org/library/std/array/join.html
If I search for dlang array join that the third hit on google
if I'm logged in, and the SECOND hit if I use an anonymous
session that gives google no information about my searching
habits.
Can confirm these search results.
As an aside, the mere formatting of the list of
template-constraints on the dlang page made me nope right out of
even bothering to figure out how to read them or what the
difference between the first and the second overload of join was.
Checking dpldocs for proper formatting and spending half a minute
making sense of it I figured that the one was for an exactly
matched element type and the other one was to allow joining a
baseClass[][] with a subClass[] or something along those lines.
Plus, it's of course really nice that we have these single pages,
but for most things you search in google you still get results
that lead you to http://dlang.org/phobos/ with pages that usually
make your scrollbar pretty tiny and forcing you to either
Ctrl+F-guess your way through the page or figuring out what
function out of a list of 10-30 functions might possibly suit
your need only to scroll back up again and repeat (or look at
another module altogether) if it doesn't. Cumbersome and annoying
(ie: slow and unproductive).
Also the information that /library even exists is new to me. I
have only discovered it through reading this post. So that much
for its discoverability (I am new to D, but I did spend probably
something like 5-10 hours bugging around phobos documentation by
this point and never really knew of /library).
Example searches I did:
http://puu.sh/mdGTt/e71cc7e459.png (only phobos)
http://puu.sh/mdGX8/24250120b1.png (first two results /phobos,
third /library)
http://puu.sh/mdH5W/31d3a2432a.png (should be
https://dlang.org/library/std/base64/base64_impl.decode.html
ideally, but the module overview pages have examples, so this is
kind of okay)
http://puu.sh/mdH8g/42a82217e0.png (none of these results mention
that you should simply cast(char[]) and then call validate on the
casted array, from what I could tell skimming through them for 5
minutes, I might have missed a mention though, which would simply
mean it is not obvious enough)
So yeah, we have that, but it should be promoted more, and the
documentation still needs lots of love (think the type of
formatting and interlinking (even to concepts!) that adams
documentation does, and of course the general deal with we need
more examples and whatnot).