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).


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)

Reply via email to