www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 5136] New: DDoc: listing methods in the 'Jump to' links may be undesirable

reply d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=5136

           Summary: DDoc: listing methods in the 'Jump to' links may be
                    undesirable
           Product: D
           Version: D2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: minor
          Priority: P2
         Component: DMD
        AssignedTo: nobody puremagic.com
        ReportedBy: ntrel-public yahoo.co.uk


--- Comment #0 from Nick Treleaven <ntrel-public yahoo.co.uk> 2010-10-30
08:23:13 PDT ---
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.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Oct 30 2010
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=5136


Jonathan M Davis <jmdavisProg gmx.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |jmdavisProg gmx.com


--- Comment #1 from Jonathan M Davis <jmdavisProg gmx.com> 2010-10-30 11:43:59
PDT ---
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.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Oct 30 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=5136


Johannes Pfau <johannespfau gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |johannespfau gmail.com


--- Comment #2 from Johannes Pfau <johannespfau gmail.com> 2010-10-30 12:17:17
PDT ---
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.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Oct 30 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=5136



--- Comment #3 from Nick Treleaven <ntrel-public yahoo.co.uk> 2010-11-01
05:23:22 PDT ---
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.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Nov 01 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=5136


Stewart Gordon <smjg iname.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |smjg iname.com
          Component|DMD                         |websites


--- Comment #4 from Stewart Gordon <smjg iname.com> 2012-03-11 10:34:20 PDT ---
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.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 11 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=5136



--- Comment #5 from Jonathan M Davis <jmdavisProg gmx.com> 2012-03-11 14:25:33
PDT ---
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.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 11 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=5136



--- Comment #6 from Stewart Gordon <smjg iname.com> 2012-03-11 15:06:51 PDT ---
(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. -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Mar 11 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=5136


Jonathan M Davis <jmdavisProg gmx.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
          Component|websites                    |DMD


--- Comment #7 from Jonathan M Davis <jmdavisProg gmx.com> 2012-03-11 15:10:31
PDT ---
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.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 11 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=5136


Brad Anderson <eco gnuk.net> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |eco gnuk.net


--- Comment #8 from Brad Anderson <eco gnuk.net> 2012-03-11 15:15:10 PDT ---
(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). -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Mar 11 2012
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=5136


Stewart Gordon <smjg iname.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
          Component|DMD                         |websites
           Severity|minor                       |enhancement


--- Comment #9 from Stewart Gordon <smjg iname.com> 2012-03-11 17:13:51 PDT ---
(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. -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Mar 11 2012