Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

On Monday, 28 December 2015 at 23:01:05 UTC, Andrei Alexandrescu 
wrote:
> The signature proper is nice. The formatting of "&&" in the 
> constraint is inconsistent, but I guess that's a matter with 
> the formatting of the code.

Yeah, that is a css bug I just forgot about getting in to 
everything else, fixed now.

> The vertical spacing post "Parameters" of 
> http://dpldocs.info/findSkip is annoying.

In a simple function it may be unnecessary but doesn't really 
hurt, while in a complex type or a function with a lot of 
parameters, it improves legibility. A type alone can be a pretty 
complex beast and can warrant the use of multiple lines.

I *might* change my mind on this, Qt puts the types on one line, 
but the real question is what they look like when I finish the 
constraint analyzer. I haven't even started implementing it yet, 
but the type of haystack is not really R1. It is actually 
"duck-typed forward range", which is gleamed from the constraint.

Qt's types are rarely more complex than a class pointer. 
Sometimes, you might see a QList<QSomething*> or a QMap<QKey, 
QValue>, but never anything like what Phobos deals in. C++ 
doesn't have D's const and immutable, it doesn't have the dip 25 
ref checker, it doesn't use much design by introspection. 
Voldemort types both simplify the signature and make the 
explanation more complex at the same time.

So what works for us may be quite different than what works for 
them.

But once I get the constraint analyzer set up and try it on more 
real world code, if it remains legible in complex cases on one 
line (which it might, I should be able to simplify stuff like 
`!isInfinite!Range && isForwardRange!Range` into something like 
"finite forward range"), I'll revisit this.


> Ideally most of these things would be adjustable via css.

Of course, it is primarily an issue of margins, and I'm mostly 
using the browser defaults for the semantic tags at this point. 
But I do want it to be good out of the box and find too much 
space to be better than too little.

> Essentially it would be fantastic if the docs contained the 
> semantic info and the formatting would be entirely shipped to 
> css.

Yes, I agree, that is one of my goals too.