Bug 5136 – DDoc: listing methods in the 'Jump to' links may be undesirable

The 'Jump to' links that appear at the top of Phobos documentation probably should not include methods of struct, class, interface because this obscures other module level tags e.g. functions. This is particularly awkward here: http://www.digitalmars.com/d/2.0/phobos/std_container.html 1. The template function 'make' is almost lost in the 'Jump to' list because of the many methods of the container types. 2. Method links are unpredictable when there are duplicate names. E.g. the 'Jump to' link to 'popFront' goes to SList:Range:popFront, but popFront is also a method of other container ranges, e.g. Array:Range. Besides removing methods, an alternative solution for (1) would be to color methods differently.

What we really need is a hierachical list of links which separates out the functions which are directly in the module from those in structs/classes and puts those in structs/classes under the links for those structs/classes - possibly with putting the links for nested structs and classes under the structs/classes which contain them.

Showing only the top level links is quite easy: In the listanchors() javascript function: ---------------------------------------------------- for (var i = 0; i < document.anchors.length; i++) { var a = document.anchors[i]; + if(a.parentNode.parentNode.parentNode.parentNode.id == "content") { var text = a.name; if (hash[text] > 0) continue; hash[text] = 1; values[n++] = a.name + } } ----------------------------------------------------- I have only tested this with one module, but it should work. It should also be possible to generate a hierarchical view using javascript, but that's some more work.

I agree with comment #1, hierarchical links would be best. That could solve the duplicate link names issue too. Thanks for the code in comment #2, I tried it for std.container and personally I think it's an improvement on the status quo, showing just 'Array BinaryHeap SList heapify make'. Not sure whether it's suitable for all modules, maybe.

The "Jump to" links aren't generated by Ddoc. They're generated by JavaScript code in the Ddoc template used for the Phobos docs. But this fact is in itself an abomination. I've just filed it as issue 7687.

I don't see much reason to care about how the jumplist is generated. The big issue is that it fails to to into account the type hierarchy at all, and that has nothing to do with javascript.

(In reply to comment #5) > I don't see much reason to care about how the jumplist is generated. The big > issue is that it fails to to into account the type hierarchy at all, and that > has nothing to do with javascript. True. But this was filed as a DMD issue, and I was explaining why this was wrong. And moreover, dealing with issue 7687 will affect how this one is tackled.

It _is_ a dmd issue. dmd generates the ddoc documentation. The javascript stuff which runs after that doesn't even _have_ the information necessary to produce the proper hierarchy. The anchor generation prevents it, because it generates anchors which have been stripped of their hierarchy.

(In reply to comment #7) > It _is_ a dmd issue. dmd generates the ddoc documentation. The javascript stuff > which runs after that doesn't even _have_ the information necessary to produce > the proper hierarchy. The anchor generation prevents it, because it generates > anchors which have been stripped of their hierarchy. Adam D. Ruppe has a pull request that includes a fix for this. https://github.com/D-Programming-Language/dmd/pull/770 I'll add a link to the actual bug for this issue as well (#6017).

(In reply to comment #7) > It _is_ a dmd issue. dmd generates the ddoc documentation. The javascript stuff > which runs after that doesn't even _have_ the information necessary to produce > the proper hierarchy. The anchor generation prevents it, because it generates > anchors which have been stripped of their hierarchy. You're wrong, it _does_ have all the information it needs, in the form of the anchor's position in the DOM. Indeed, I've managed to fix it by adding one line to the JS code: for (var i = 0; i < document.anchors.length; i++) { var a = document.anchors[i]; var text = a.name; if (a.parentNode.parentNode.parentNode.tagName == "DD") continue; if (hash[text] > 0) continue; hash[text] = 1; values[n++] = a.name } While it would be nice to have a hierarchical list of links, it's distinct from the reporter's request, and so warrants a separate RFE. From a DMD point of view, it's a matter of the Ddoc macro system providing access to the full hierarchical name of the symbol.

This is largely solved by ddox, see the updated version here: http://dlang.org/library/std/container.html. Marking as worksforme.

Implemented hierarchically-grouped jump to links: https://github.com/D-Programming-Language/dlang.org/pull/726 As regards ddox, personally I'd rather browse module docs all in the same page, without having to keep waiting for pages to load each time I click a symbol.