Ready to make page-per-item ddocs the default?

[Manu via Digitalmars-d]

On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d at puremagic.com> wrote:
> Let's crowdsource the review. Please check the entries linked from here:
> http://dlang.org/library/index.html.
>
> Andrei

Very first function I looked at: http://dlang.org/library/std/string/format.html

I find all the horizontal bar's throughout the docs quite noisy and
tiring, and somewhat antiquated stylistically.

I expected the parameters to jump out at me, but I didn't notice that
that block surrounded by black lines and bold headings was actually
the parameter list. I don't think I need headings to tell me which
column is the name and which is the description. Ie, the parameters
didn't jump out at me, the noise surrounding them did, and distracted
me from the parameters themselves.

There's obviously a bug here where the text is red too.

My suggestions to make that page look more professional:

* Prototype needs proper syntax highlighting, and elements (builtin
types, types, template args, runtime args, and the function name
itself) need to be styled distinctly (and tastefully).
* The noise around the parameter listing can be removed completely.
* The parameter name string in the parameter listing should match the
styling of the prototype, so you can immediately recognise the thing
in the prototype's description on the page.
* The coloured box that houses the prototype is 6 times wider than it
needs to be (on my monitor). I think it should be horizontally sized
to fit the content.
* Authors, license, and other uninteresting information should be
spaced from the content (give an extra line-break or 2), and also the
text should be significantly smaller. This is, literally, the
fine-print.

Comment box at the bottom is awesome!

Taking another random sample: http://dlang.org/library/std/csv.html

My previous criticisms stand equally.
I feel like 'see also' should be the last thing before the 'fine
print', not the first thing.

Clicking through to see a class:
http://dlang.org/library/std/csv/csv_exception.html

Prior criticisms apply, but looks okay otherwise.
There is 'fields' and 'methods', but they look the same. This is
unexpected, since methods are functions, with return types, and
arguments... why can't I see those?

I'll leave it there for a moment.


How do we style this stuff? Is there some way that we can experiment
with styling ourselves?