Broken links on generated documentation #7127

diegodiasm · 2019-07-18T12:55:38Z

Browsing the doxygen documentation of L4Re (https://l4re.org/doc/) I noticed that the link for the documentation of some C++ classes in the search bar is broken. For example, while searching for 'Task', two results come out in the search bar. Clicking on the first takes the user to the C interface, while clicking on the second result takes no effect.

I suspect this may be related to the fact that the name 'Task' is used to name two interfaces (one in C, one in C++), but I also noticed that both interfaces for Factory are both named 'Factory', and there the links for each individual interface work as expected.

Looking into the HTML code of the page in the Chrome DevTools, I noticed that when searching for 'Factory' (which is the case where the link actually works), if I click over the link in the result panel in the search bar, it updates the SRChildren element adding the attribute:

style="display: block;"

This does not happen when I search for 'Task'. Two results appear, but only one of the links has an effect when clicked on. I also noticed that if I manually edit the content of the page in Chrome DevTools by adding

style="display: block;"

to

<div class="SRChildren" classname="SRChildren">

then it expands the sub-menu and shows the link for the Task class documentation.

Looking at the source codes for both classes (Factory/Task), I could not spot anything that was able to justify this behaviour. I wonder if this is a bug in Doxygen, or may it be some configuration missing on the source code of L4Re which is causing the link to be broken.

Link for the sources (Task C/C++ and Factory C/C++) are given here:

Task C++ Interface
[In Doxygen] https://l4re.org/doc/task_source.html
[In Github] https://github.com/kernkonzept/l4re-core/blob/master/l4sys/include/task

Task C interface
[In Doxygen] https://l4re.org/doc/task_8h_source.html
[In Github] https://github.com/kernkonzept/l4re-core/blob/master/l4sys/include/task.h

Factory C++ Interface
[In Doxygen] https://l4re.org/doc/factory_source.html
[In Github] https://github.com/kernkonzept/l4re-core/blob/master/l4sys/include/factory

Factory C Interface
[In Doxygen] https://l4re.org/doc/factory_8h_source.html
[In Github] https://github.com/kernkonzept/l4re-core/blob/master/l4sys/include/factory.h

I've tried compile the documentation myself with two versions of Doxygen: 1.8.13 and 1.8.15 (the latest), but I saw no difference with respect to the broken link.

The text was updated successfully, but these errors were encountered:

albert-github · 2019-07-18T13:38:53Z

Is it sufficient to process the 2 .h files and 2 files without extension mentioned in the question?
Important is also the used Doxyfile and eventualy other configuration files.

Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent.

diegodiasm · 2019-07-19T16:36:14Z

I couldn't construct a self-contained example to trigger this problem. However, a colleague looked the generated HTML file, and he noticed that the id attribute of distinct <div> elements which are contained in the result box are not unique. In this case, there are two <div> elements with the id attribute set to SR_task. In my attempt to reproduce the problem using 4 distinct files (2 headers + 2 classes), Doxygen always succeeded to create the <div> components in a order where this problem in the results box was not observable, as the SR_... component always came before than the link for the group in the results box.

We suspect that the Toggle function in

'javascript:searchResults.Toggle("SR_task")'

searches for the first <div> element in the page that is named SR_task and tries to modify it, but in the case of the C++ Interface for Task the occurrence that should be modified is the second in the HTML file. Next is snippet of the HTML code of the results box:

<body class="SRPage">
  <div id="SRIndex">
    <div class="SRStatus" id="Loading" style="display: none;">
      Loading...
    </div>
    <div id="SRResults">
      <div id="SR_task" class="SRResult" classname="SRResult"
      style="display: block;">
        <div class="SREntry" classname="SREntry">
          <a id="Item1" onkeydown=
          "return searchResults.Nav(event,1)" onkeypress=
          "return searchResults.Nav(event,1)" onkeyup=
          "return searchResults.Nav(event,1)" class="SRSymbol"
          classname="SRSymbol" href="../group__l4__task__api.html"
          target="_parent">Task</a>
        </div>
      </div>
      <div id="SR_thread" class="SRResult" classname="SRResult"
      style="display: none;">
        <div class="SREntry" classname="SREntry">
          <a id="Item2" onkeydown=
          "return searchResults.Nav(event,2)" onkeypress=
          "return searchResults.Nav(event,2)" onkeyup=
          "return searchResults.Nav(event,2)" class="SRSymbol"
          classname="SRSymbol" href=
          "../group__l4__thread__api.html" target=
          "_parent">Thread</a>
        </div>
      </div>
      <div id="SR_task" class="SRResult" classname="SRResult"
      style="display: block;">
        <div class="SREntry" classname="SREntry">
          <a id="Item15" onkeydown=
          "return searchResults.Nav(event,15)" onkeypress=
          "return searchResults.Nav(event,15)" onkeyup=
          "return searchResults.Nav(event,15)" class="SRSymbol"
          classname="SRSymbol" href=
          'javascript:searchResults.Toggle("SR_task")'>Task</a>
          <div class="SRChildren" classname="SRChildren">
            <a id="Item15_c0" onkeydown=
            "return searchResults.NavChild(event,15,0)" onkeypress=
            "return searchResults.NavChild(event,15,0)" onkeyup=
            "return searchResults.NavChild(event,15,0)" class=
            "SRScope" classname="SRScope" href=
            "../classL4_1_1Task.html" target=
            "_parent">L4::Task</a><a id="Item15_c1" onkeydown=
            "return searchResults.NavChild(event,15,1)" onkeypress=
            "return searchResults.NavChild(event,15,1)" onkeyup=
            "return searchResults.NavChild(event,15,1)" class=
            "SRScope" classname="SRScope" href="../task.html"
            target="_parent">(Global Namespace)</a><a id=
            "Item15_c2" onkeydown=
            "return searchResults.NavChild(event,15,2)" onkeypress=
            "return searchResults.NavChild(event,15,2)" onkeyup=
            "return searchResults.NavChild(event,15,2)" class=
            "SRScope" classname="SRScope" href=
            "../classL4Re_1_1Env.html#a8be92795e470144b5acb15de07ea0c95"
            target="_parent">L4Re::Env::task()</a><a id="Item15_c3"
            onkeydown="return searchResults.NavChild(event,15,3)"
            onkeypress="return searchResults.NavChild(event,15,3)"
            onkeyup="return searchResults.NavChild(event,15,3)"
            class="SRScope" classname="SRScope" href=
            "../classL4vcpu_1_1Vcpu.html#ad3ef11adf9662db3feed1b40208032eb"
            target="_parent">L4vcpu::Vcpu::task()</a>
          </div>
        </div>
      </div>
      <div id="SR_task_2eh" class="SRResult" classname="SRResult"
      style="display: block;">
        <div class="SREntry" classname="SREntry">
          <a id="Item16" onkeydown=
          "return searchResults.Nav(event,16)" onkeypress=
          "return searchResults.Nav(event,16)" onkeyup=
          "return searchResults.Nav(event,16)" class="SRSymbol"
          classname="SRSymbol" href="../l4_2sys_2task_8h.html"
          target="_parent">task.h</a>
        </div>
      </div>
    </div>
  </div>
</body>

If we use the Developer Tools in Chrome to edit the page and rename the id of the first <div> element in the results box, then the expansion of the <div> element works as it should.

I hope this information is useful to give you a hint about what is causing the problem. If I succeed to provide a minimal working example, I will post it here.

albert-github · 2019-07-19T17:06:47Z

Sometimes it is very hard to create a minimal example, pity that you didn't succeed.
So best would be that we clone https://github.com/kernkonzept/l4re-core and run doxygen over it.
As this is a new package, what is the sequence of commands for generating the documentation with the problem?

diegodiasm · 2019-07-19T17:07:52Z

I've just succeeded to create a minimal example! Here it goes!
src.zip

albert-github · 2019-07-19T17:32:29Z

I found the example, but I didn't yet find the place where the toggle is (HTML page), maybe you can give me a hint.
I think I found the place you meant, you spoke about the "result box" meaning when giving in the "search box" the corresponding drop down. I entered in the "search box" just a 't' and got 2 items with the name "Task", clicking the first one results in a jump to the page file:///D:/speeltuin/issue_7127/src/gen-doc_1_8_15/html/group__l4__task__api.html, whilst the second one gives doesn't do anything (with ctrl-click the address bar of the new tab gives: javascript:searchResults.Toggle("SR_task")).

Renaming the group in Task.h:

\defgroup l4_task_api Task

to

\defgroup l4_task_api Task_h

solves the problem, but is not required solution as the texxt "task_h" would also appear in the output.

I just checked the master version and here the problem is also still present.

Make identifier in the `.js` files unique (they are only used internally)

albert-github · 2019-07-20T09:28:32Z

I've just pushed a proposed patch, pull request #7133

albert-github · 2019-07-26T09:09:13Z

Code has been integrated in master on github (please don't close the issue as this will be done at the moment of a release).

doxygen · 2019-08-08T17:45:45Z

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.8.16.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).

albert-github added the needinfo reported bug is incomplete, please add additional info label Jul 18, 2019

albert-github added bug and removed needinfo reported bug is incomplete, please add additional info labels Jul 20, 2019

albert-github added a commit to albert-github/doxygen that referenced this issue Jul 20, 2019

issue doxygen#7127 Broken links on generated documentation

7fec9f5

Make identifier in the `.js` files unique (they are only used internally)

albert-github added the fixed but not released Bug is fixed in github, but still needs to make its way to an official release label Jul 26, 2019

crackwitz mentioned this issue Aug 5, 2019

access to split doc opencv/opencv#8057

Closed

doxygen removed the fixed but not released Bug is fixed in github, but still needs to make its way to an official release label Aug 8, 2019

doxygen closed this as completed Aug 8, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Broken links on generated documentation #7127

Broken links on generated documentation #7127

diegodiasm commented Jul 18, 2019

albert-github commented Jul 18, 2019

diegodiasm commented Jul 19, 2019 •

edited

albert-github commented Jul 19, 2019

diegodiasm commented Jul 19, 2019 •

edited

albert-github commented Jul 19, 2019 •

edited

albert-github commented Jul 20, 2019

albert-github commented Jul 26, 2019

doxygen commented Aug 8, 2019

Broken links on generated documentation #7127

Broken links on generated documentation #7127

Comments

diegodiasm commented Jul 18, 2019

albert-github commented Jul 18, 2019

diegodiasm commented Jul 19, 2019 • edited

albert-github commented Jul 19, 2019

diegodiasm commented Jul 19, 2019 • edited

albert-github commented Jul 19, 2019 • edited

albert-github commented Jul 20, 2019

albert-github commented Jul 26, 2019

doxygen commented Aug 8, 2019

diegodiasm commented Jul 19, 2019 •

edited

diegodiasm commented Jul 19, 2019 •

edited

albert-github commented Jul 19, 2019 •

edited