On Mon, 28 Nov 2011 15:38:49 -0500, Piotr Szturmaj <[email protected]>
wrote:
Hi,
I'm trying to make ddoc index more readable. Here are some early
results:
http://bot.neostrada.pl/dpl.org/std.datetime.html
Do you know some free icons of class, enum, function, etc? I'm thinking
of something like this: http://msdn.microsoft.com/en-us/library
/y47ychfe%28v=vs.80%29.aspx
Just an FYI, this does not render properly on opera. I have only have a
top-level index that does not operate (and yes, I have javascript on).
My personal opinion is that the index should not rely on javascript
whatsoever. If anything, a collapsable index of everything should be
available at the top (expanded by default if javascript is disabled).
There should only be one level -- show all or hide all.
In general, DDoc suffers from so many deficiencies, fixing the index seems
like wasted effort. I'd prefer improvements like have one page per item
(class, function, etc) similar to doxygen. This would turn behemoths such
as std.datetime into manageable doc pages. I also think a vastly
important (and for some reason ignored by ddoc) feature of documentation
generators is cross referencing. The whole benefit of having a computer
generate documentation from source is that it knows how the source is
related. That should all be reflected. For instance, I should be able to
have a clickable inheritance tree for a class, and be able to have
clickable links to overridden methods. Any examples should have clickable
links to the items being used. These improvements would improve the docs
by 2 orders of magnitude, whereas fixing the index is a trivial
improvement.
Not that the index couldn't use improvement, however I understand the
reluctance to take up the bigger ddoc tasks, I would not be able to do it.
-Steve
