Please fix internal links in class documentation

In the “old” ROOT documentation, internal web links to class members were preserved across releases.
So, (almost always) any link given to some method was valid even years after the post was written.
An example:
TGraph::Integral from ROOT 5.34
TGraph::Integral from ROOT 5.30

Unfortunately, the “new” way of the documentation generator creates new distinct links (almost?) each time it is executed.
As a result, links in forum posts become quickly invalid.
An example:
TGraph::Integral from ROOT master as of 2018.05.23
TGraph::Integral from ROOT master as of 2017.05.05

Please, fix this problem.
Posts in this forum are very often “reused” (and read by people even years after they were created) and the links given inside should be kept “valid”.

1 Like

Part of the problem here is that the links point to the master documentation and the links there get “randomly” assigned by doxygen every time the documentation is compiled. If instead links to particular versions were posted then the links would hopefully not be regenerated as that version has been finalized and released. Somehow the master version needs to be harder to find and instead the latest recommended version should be the go to for documentation, this also avoids issues where new features are added to the master documentation which users expect to be in the recommended release.

Note that in the “old” ROOT 5 documentation, all links were preserved in the ROOT 5 master, too (the only change in links was “/html/” for the master versus “/html534/” for 5.34 versus “/html530/” for 5.30).

We need this same approach now.

Olivier strongly encourages people to give links (in posts) to the current master, but this quickly creates broken posts.

So, we need a way to convince doxygen to generate “stable” / “predictable” links (instead of “random” strings).

Seems to me only the links to the methods are not preserved, Right ? For instance the link to the TGraph class is always root.cern/doc/master/classTGraph.html. I agree with you that it is really annoying to have the links to the methods changing. I will check if some solution exists .

We also regenerate (every night) older versions of the documentation, for instance to fix mistakes or typos. So even the “non master” version are changing.

I investigated a bit more and found some information here and there. According to what I saw, the naming of the “funstions’ URL” is done according to the functions’ prototypes, Therefore if the function signature does not change it should be the same among various documentation (re)generation. And indeed it seems to be the case. I just take here as example a function I know for sure it has not changed between 6.10 and the current master: TGaxis::ChangeLabel . Here are the URL for 6.10 and master:

 https://root.cern/doc/master/classTGaxis.html#a8ef5ba035d846add3902cd714336eaac
https://root.cern.ch/doc/v610/classTGaxis.html#a8ef5ba035d846add3902cd714336eaac

As you can see they are exactly the same.

And even if I generate a short version of the doc locally on my machine I get the same URL:

file:///Users/couet/rootdoc/html/classTGaxis.html#a8ef5ba035d846add3902cd714336eaac

Well, maybe they depend on the doxygen version:
https://root.cern.ch/doc/v606/classTGraph.html#a635997a6d81e4e89529aaf1819cf7533
https://root.cern.ch/doc/master/classTGraph.html#a06b6dfc69d4fe9336ade71a47864f974
So, as soon as you “upgrade” doxygen, all links will again be invalidated.

Ah … yes this can be … I will ask on the doxygen forum.

Maybe you could ask them if instead of these random “#a8ef5...” strings we could again get “#TGraph:Integral” or something like this.

Done… waiting the answer.

It does not seems to be that simple. I took an other example of a very old method which for sure has not changed.THistPainter::PaintArrows . I looked at the oldest version of the reference guide we have generated with doxygen: 6.06 … versus the master version. I get:

https://root.cern.ch/root/html606/classTHistPainter.html#a8d22919405e4f641344c5d61cc83ba0a
     https://root.cern/doc/master/classTHistPainter.html#a8d22919405e4f641344c5d61cc83ba0a

… the same URL …

the doxygen versions are 1.8.9 and 1.8.13 …

So may be there is some other hidden rules triggering the name change … I leave my question on the doxygen forum. They may tell me if there is something hidden we have not seen.

Looking at the links in your last post, I noticed that you used “/root/html606/” while I used “/doc/v606/”.

It seems that, for “TGraph::Integral”, they produce different links starting with ROOT 6.08:
https://root.cern.ch/doc/v608/classTGraph.html#a06b6dfc69d4fe9336ade71a47864f974
https://root.cern.ch/root/html608/classTGraph.html#a635997a6d81e4e89529aaf1819cf7533

Note: starting from ROOT 6.10, “/doc/v610/” exists and “/root/html610/” does NOT.

Just an idea … can one somehow convince doxygen to emulate c++ compiler’s name mangling (“man c++filt”)?

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.