On Wednesday, 30 December 2015 at 14:25:24 UTC, default0 wrote:
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.
Aye, it is a complete mess and virtually *nobody* bothers looking
at them. (BTW, dmd has the same problem in error messages. I plan
to format them eventually too, with some kind of highlighting of
passed and failing clauses. I already did a proof of concept for
ordinary overloading functions and it wasn't actually that hard.
I just wish I didn't have other things to do!)
New people are often outright scared away from everything and
left with the impression that D is an experts-only language. The
Phobos devs know this and have been trying to add more examples -
a good, necessary step - but that isn't the whole problem.
When users modify the examples and they fail to compile, they
need to understand what's going on. The compiler will complain in
terms of those ugly constraints, not in terms of fixed, working
examples. They need some way of understanding what it is saying.
Also: I plan to add a doc section called "diagnostics" with
sample error messages and translations. I've actually considered
doing this before but was stopped by concerns over vertical space.
No kidding, when writing ddoc, I worry about it taking up too
much space on the page and will cut content out as a result. If
the prototype is compressed, it just leaves a mental bug that
says space must matter, use it sparingly.
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.
The join overloads are basically:
#1: array of arrays joined by an array
join(["a", "b", "c"], ", "); // the joiner is an array
-> "a, b, c"
#2: array of arrays joined by an element
join(["a", "b", "c"], ' '); // the joiner is an element
-> "a b c"
There is no example for form #2 in the documentation. (BTW I
think the examples should be commented too.)
#3: array of arrays joined without anything
join(["a", "b", "c"])
-> "abc"
Nothing about inheritance in there, the constraints talk about
ElementType!RoR which means (conceptually) it is stripping the
"[]" off a type, so for "int[]", it returns "int".
That should probably just be written in the text. (That's another
thing people tell me, they come in with a question and I can give
them a quick answer, then they ask "why didn't the docs just put
it that simply?" And a few times, I go to open a PR but get
stalled by the process somewhere....)
But there's a LOT of functions in Phobos so I am trying to
automate this because while I can write it for any individual
function by hand, writing it for ALL the functions is going to
take more time than I have.
Cumbersome and annoying (ie: slow and unproductive).
absolutely.
Also the information that /library even exists is new to me. I
have only discovered it through reading this post.
Right. New users either don't know about it because it doesn't
get linked to much and thus has lower page rank (unless you have
already trained Google through D searches to favor D results), or
they do find it and are confused as to what version it refers to.
There's been a few people who come to this newsgroup saying
"these docs look old, what's up with it?" If they hit the disqus
comment, it says "recent activity, 2 years ago" which furthers
this impression.
(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)
When you mentioned this before, I went to add it to the docs but
couldn't find a good place to put it. The vertical space brain
bug hurt me on base64 itself, then the question of linking hurt
me when thinking of putting it somewhere else like the wiki, then
the question of process killed me when I went to add a new page!
It was actually this experience that tipped me over the edge and
I decided to start working on doc infrastructure myself. (I've
spent a good amount of time this year trying to fix ddoc itself -
starting with the `code` syntax in January - but ddoc itself is
only part of the problem)
