Look at almost any page in the D2 Phobos docs.
If you have JavaScript enabled, you'll see that just after loading the page it adds a set of "Jump to:" links.
The code to do this has been made part of the Phobos Ddoc template. It works by scanning the document for anchors and then listing them.
This is ridiculous. What was the point of writing this JS code to get around a limitation of Ddoc, rather than fixing the limitation?
Ddoc should be able to generate this list of links itself. This way, it would work regardless of whether the user has JS enabled.
Moreover, it would be good to give the user of Ddoc the choice of listing only module-level symbols or all documented symbols in the module.
Comment #1 by nick — 2014-12-24T16:59:11Z
Stewart Gordon from comment #0)
> This is ridiculous. What was the point of writing this JS code to get
> around a limitation of Ddoc, rather than fixing the limitation?
Using JS is much easier than extending dmd as long as dmd uses a subset of C++.
> Moreover, it would be good to give the user of Ddoc the choice of listing
> only module-level symbols or all documented symbols in the module.
I've made a pull for Issue 5136 which (essentially) solves this.
Comment #2 by smjg — 2014-12-25T23:56:09Z
(In reply to Nick Treleaven from comment #1)
> Using JS is much easier than extending dmd as long as dmd uses a subset of
> C++.
I have trouble believing it can be this difficult, given that the compiler must rely on quite complex data structures anyway. What particular C++ feature would make implementing this feature easier if only it were in the subset that DMD is written in?
Comment #3 by nick — 2014-12-27T11:47:38Z
Using JS is easier than C++, whatever the subset.
Comment #4 by smjg — 2014-12-27T19:09:54Z
So why wasn't the whole of DMD written in JS? :)
Seriously ... so you mean that Walter couldn't be bothered at the time to spend the time working out how to improve DMD, so for the meantime he just wrote this JS hack?
Comment #5 by nick — 2014-12-30T17:15:14Z
I was talking about for HTML generation. At the time the JS was first added, I don't think ddoc was in a good state, it has since improved significantly.
Comment #6 by smjg — 2015-01-30T12:12:35Z
(In reply to Nick Treleaven from comment #5)
> I was talking about for HTML generation. At the time the JS was first added,
> I don't think ddoc was in a good state, it has since improved significantly.
But Ddoc isn't an HTML generator. It's a macro-based system capable of generating documentation in a variety of formats.
Comment #7 by nick — 2015-01-30T12:41:12Z
You asked why JS was used, I explained. Please implement this if you like.
Comment #8 by Tachyon165 — 2015-05-31T03:38:24Z
More minor, but whenever or however "Jump to" links are updated in the future, I noticed the ordering seems to be off:
If there are more than 9 overloads, the Jump to links read:
"10 11 2 3 4 5 6 7 8 9"
In other words, seems to be sorted lexicographically by the string value rather than numerically by the index value.
An example of this can be seen at: http://dlang.org/phobos/std_conv.html#.toImpl
Comment #9 by smjg — 2015-06-09T11:40:39Z
(In reply to Doug Nickerson from comment #8)
> More minor, but whenever or however "Jump to" links are updated in the
> future, I noticed the ordering seems to be off:
This bug report is about the shortcoming in Ddoc's capabilities. Any bug in dlang.org's JS workaround is a separate issue, so I think it should have a separate bug report. Though it's useful to have this note here to make sure that it isn't overlooked when implementing the feature in Ddoc.
Of course, once this one is implemented, the bug with the JS workaround will become a non-issue.
Comment #10 by robert.schadek — 2024-12-13T17:59:02Z