On 2011-11-28 22:18, Steven Schveighoffer wrote:
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
I completely agree. Descent has quite a good ddoc generator, I think it
cross references everything. But on the other hand it uses frames.
--
/Jacob Carlborg
