reference documentation format

[Jonathan M Davis]

On Sunday, November 20, 2011 13:20:00 Nicolae Mihalache wrote:
> If this module contains only functions, it looks fine. But I see it's
> manually written.
> 
> I would think it is possible to generate an index with all the functions,
> classes, structs, etc and with a short description of each and with a link
> to the full description.
> 
> Currently all the top level functions, classes, structs, method of classes
> and structs appear in one list and it's difficult to say which is what.
> 
> Maybe I'm too biased by javadoc. I will try to work a bit more with D and
> perhaps I will have a better idea.

There's no reason why ddoc shouldn't be capable of generating a nice set of 
links at the top that give proper structure. The problem is that the anchors 
that it currently generates only hold the function name, so all hierarchical 
information is lost. Once that's fixed, then it shouldn't be a problem to have 
hierarchical links, but at the moment, it requires creating the links by hand, 
and in the case where multiple functions in the same file have the same name 
(including between user-defined types) results in a set of identical anchors, 
so you can't link to them individually, so you _can't_ have proper links in 
that case without editing the file after it's been generated - which definitely 
wouldn't work with the official docs and would obviously be a pain regardless.

I expect that the situation will be fixed eventually, but until then, the links 
on ddoc are limited in how well-structured they can be. Modules of only free 
functions can do fairly well as long the links are created by hand (e.g. 
std.algorithm), but modules which define types are currently out of luck (e.g. 
std.datetime).

- Jonathan M Davis