Improved Phobos dox

[Jonathan M Davis]

On Sunday, September 15, 2013 19:35:06 Joseph Rushton Wakeling wrote:
> On 15/09/13 13:32, Andrej Mitrovic wrote:
> > It's not an improvement at all. Ctrl+F doesn't work with this (like
> > you mentioned), and the items list is not even sorted
> > alphabetically(!), so now we have to hunt down a symbol before we can
> > jump to it. Also, what used to be just one step (click), now becomes
> > more (click, scroll, click).
> 
> Agree, being able to use Ctrl+F is crucial.  Anything that kills that is a
> problem.

Yeah. It feels a lot like when you can't resize a Window like Microsoft won't 
let you done with the dialog for setting environment variables. When I mess 
with my PATH in Windows, I typically have to copy it elsewhere, edit it, and 
copy it back. This feels a lot like that except that it relates only to finding 
data and not editing it. I would much rather have the list of links at the top 
that we have right now.

Really, the main problems with the current list of links relate to the fact 
that it completely ignores scoping.

1. All of the functions with the same name end up with the same anchor even if 
they're inside a struct or class (so std.datetime ends up with 3 day links - 
for SysTime, DateTime, and Date - and they all end up just going to SysTime, 
because it just so happens to be first).

2. You just get a long list of functions with no organization and no 
indication of what type (if any) they belong to. You should see something like 
SysTime.year, DateTime.year, Date.year rather than year three times in a row. 
And the links as a whole really should be organized by the type that they're 
in (e.g. all of the SysTime functions would be grouped together and separate 
from functions in the module which are in other types or which are free). 
Right now, all we get is a big long list with no hierarchy whatsoever.

The case of std.algorithm shows the need to organize free functions based on 
what they do, but I think that that pretty much has to be done by hand, and if 
it's really needed it, it implies that separating the module (as we've 
discussed) is probably a good idea. The hierarchy of the functions themselves 
however _is_ something that can be done programmatically and would really help 
any module which has any user-defined types in it.

- Jonathan M Davis