On Tue, Mar 27, 2012 at 11:59 PM, Jonathan M Davis <span dir="ltr"><<a href="mailto:jmdavisProg@gmx.com">jmdavisProg@gmx.com</a>></span> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="HOEnZb"><div class="h5">On Tuesday, March 27, 2012 22:20:56 H. S. Teoh wrote:<br>
> On Wed, Mar 28, 2012 at 06:58:45AM +0200, Alex Rønne Petersen wrote:<br>
> > On 28-03-2012 06:13, James Miller wrote:<br>
> [...]<br>
><br>
> > >I think one more thing that needs some changing is the usability of<br>
> > >the documentation, right now you get a dense list at the top, in<br>
> > >mostly-alphabetical order (I think it puts caps first, then lower<br>
> > >case) and then you get a massive list of classes and functions that<br>
> > >are difficult to navigate.<br>
> ><br>
> > I think basically everyone dislikes this.<br>
><br>
> [...]<br>
><br>
> The docs for classes and functions really need to be properly<br>
> categorized according to utility, and not just presented in the order in<br>
> the code or some arbitrary ordering (like alphabetical). Alphabetical is<br>
> OK if you already know what you're looking for, but is horrible for<br>
> newbies who have no idea where to even start. (And arguably even if you<br>
> know what you want, alphabetical is only useful if you already know the<br>
> exact name... otherwise you'd still want to look it up by category<br>
> instead of name.)<br>
<br>
</div></div>Alphabetical isn't all that big a deal if the docs would just maintain the<br>
hierarchy (e.g. putting the functions of a class with a class rather than<br>
lumping everything in the list at the top). But unfortunately, ddoc doesn't<br>
really support that right now. Some modules do have additional stuff at the top<br>
for organizing their stuff beyond lumping it together (e.g. std.alorithm and<br>
std.container), but ddoc itself needs some improvements with regards to<br>
anchors and the like for the links at the top to really be organized like they<br>
should be.<br>
<span class="HOEnZb"><font color="#888888"><br>
- Jonathan M Davis<br>
</font></span></blockquote></div><br><div>Adam has a pull request addressing this issue <<a href="https://github.com/D-Programming-Language/dmd/pull/770">https://github.com/D-Programming-Language/dmd/pull/770</a>>.  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.</div>
<div><br></div><div>Regards,</div><div>Brad Anderson</div>