Better docs for D (WIP)

Adam D. Ruppe via Digitalmars-d-announce digitalmars-d-announce at puremagic.com
Wed Dec 30 07:30:05 PST 2015


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)



More information about the Digitalmars-d-announce mailing list