Improved Phobos dox

[H. S. Teoh]

On Sun, Sep 15, 2013 at 12:14:14AM -0700, Andrei Alexandrescu wrote:
> I finally gathered strength to rebase
> https://github.com/D-Programming-Language/dlang.org/pull/271
> manually, which was every bit as involved as I feared.
> 
> I hope I didn't mess up anything, reviews appreciated.
> 
> That diff includes a new page navigation scheme. (Wasn't the main
> purpose of the diff but found it a nice perk.) I see it as a
> transitional stage toward the larger transition to
> one-page-per-entity that Sönke has proposed.
> 
> Check out the new navigation at
> http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list
> as the top gets replaced by a slick drop-down. Once you jump to a
> name, you can go back by pressing the up arrow on the right or
> simply go to top.
[...]

Not bad. I'd suggest replacing the default selection on the "slick"
drop-down with a more helpful message, like "choose a declaration..." or
something like that, instead of just a down arrow with lots of trailing
blank space.

The one thing that I do NOT like, is the lack of indentation for
aggregate members. For example, struct Appender's members aren't
visually differentiated from other module-level symbols, which makes the
documentation VERY confusing. For reference, this is the format I use
for my own ddocs:

	http://eusebeia.dyndns.org/~hsteoh/tmp/doc/mda

which are generated by the minimalistic macros here:

	https://github.com/quickfur/Viola-ddoc-macros

The nesting of various identifiers are deliberately made very explicit
visually (see, for example, the docs for `struct IndexRange`), so
there's no confusion as to what symbol belongs in which aggregate. I
think this is indispensible for the docs to be useful to newbies.


T

-- 
Error: Keyboard not attached. Press F1 to continue. -- Yoon Ha Lee, CONLANG