Documentation 'quick index'

[Jacob Carlborg]

On 2011-11-28 22:18, Steven Schveighoffer wrote:
> On Mon, 28 Nov 2011 15:38:49 -0500, Piotr Szturmaj
> <bncrbme at jadamspam.pl> 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