Documentation 'quick index'

[Jonathan M Davis]

On Monday, November 28, 2011 22:17:02 Piotr Szturmaj wrote:
> Jonathan M Davis wrote:
> > On Monday, November 28, 2011 22:45:17 Vladimir Panteleev wrote:
> >> On Mon, 28 Nov 2011 22:38:49 +0200, 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
> >> 
> >> I think that for something like this to have full benefit, DDoc would
> >> need to be fixed so that generated anchors include their context.
> > 
> > Yeah. I'd have made std.datetime's links similar to what's in
> > std.algorithm, but as long as anchors aren't unique, there's not much
> > point.
> 
> I think that <a name="mangledName"></a> would be the best approach. This
> would make tree generation easier (currently it parses text near to
> anchor) and all anchors would be unique.

Using the mangled name would help deal with overloaded functions but would be 
completely unnecessary for classes and structs. Simply doing something like 
#SysTime.year would make it unique enough for them. But the manged names may 
be preferable, since then overloaded functions could be distintguished (though 
the anchors would then be a lot less human-readable).

> > Whether this specific proposal is really the best way to go or not, I
> > don't know, but there's no question that the links should represent the
> > hierarchy of the module.
> 
> Do you mean sort order? This can be made switchable with single checkbox.

No. I mean the hierarchy - as in understanding the difference between free 
functions and member functions. The links at the top should show member 
functions (and member variables if they're not private) as being part of the 
type that they're part of, not as free functions. The example that the OP 
gives does that, whereas the current situation just gives a list of links with 
no regard to what they point to. So, while some of the details of his 
presentation may not be the best, the basic idea is solid. Unfortunately, as 
long as the links are non-unique, it doesn't help much - particularly for 
std.datetime.

- Jonathan M Davis