reference documentation format

[Nicolae Mihalache]

I also expect that the situation will be fixed eventually, but in the
meanwhile, can I issue a feature request?
I see the Issues page is disabled on the dmd github page:
https://github.com/D-Programming-Language/dmd
Is there any reason for that?


On Sun, Nov 20, 2011 at 1:31 PM, Jonathan M Davis <jmdavisProg at gmx.com> wrote:
> 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
>