On Tue, Mar 27, 2012 at 11:59 PM, Jonathan M Davis <jmdavisProg@gmx.com> wrote:
On Tuesday, March 27, 2012 22:20:56 H. S. Teoh wrote:
> On Wed, Mar 28, 2012 at 06:58:45AM +0200, Alex Rønne Petersen wrote:
> > On 28-03-2012 06:13, James Miller wrote:
> [...]
>
> > >I think one more thing that needs some changing is the usability of
> > >the documentation, right now you get a dense list at the top, in
> > >mostly-alphabetical order (I think it puts caps first, then lower
> > >case) and then you get a massive list of classes and functions that
> > >are difficult to navigate.
> >
> > I think basically everyone dislikes this.
>
> [...]
>
> The docs for classes and functions really need to be properly
> categorized according to utility, and not just presented in the order in
> the code or some arbitrary ordering (like alphabetical). Alphabetical is
> OK if you already know what you're looking for, but is horrible for
> newbies who have no idea where to even start. (And arguably even if you
> know what you want, alphabetical is only useful if you already know the
> exact name... otherwise you'd still want to look it up by category
> instead of name.)

Alphabetical isn't all that big a deal if the docs would just maintain the
hierarchy (e.g. putting the functions of a class with a class rather than
lumping everything in the list at the top). But unfortunately, ddoc doesn't
really support that right now. Some modules do have additional stuff at the top
for organizing their stuff beyond lumping it together (e.g. std.alorithm and
std.container), but ddoc itself needs some improvements with regards to
anchors and the like for the links at the top to really be organized like they
should be.

- Jonathan M Davis

Adam has a pull request addressing this issue <https://github.com/D-Programming-Language/dmd/pull/770>.  It basically makes anchors the full hierarchy of the symbol but without the containing module as that would be redundant and break almost all existing links.

Regards,
Brad Anderson