On Tue, Mar 27, 2012 at 11:59 PM, Jonathan M Davis <[email protected]>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
