DOC: Remove Doxygen `\ref` command in module description

[jhlegarreta]

Remove group/module linking Doxygen \ref command in module description. Non-working as-is.

Introduced in commit a0d0b4c.

PR Checklist

• [X] No API changes were made (or the changes have been approved)
• [X] No major design changes were made (or the changes have been approved)

[jhlegarreta]

Cross-referencing https://github.com/InsightSoftwareConsortium/ITK/pull/3649#issuecomment-1260845948.

Importantly enough, I have realized that the \ref command is actually working on *.dox files, e.g. the Geometry Representation Objects section in: https://insightsoftwareconsortium.github.io/ITKDoxygen/modules.html which leads to https://insightsoftwareconsortium.github.io/ITKDoxygen/group__Geometry.html

which are generated from: https://github.com/InsightSoftwareConsortium/ITK/blob/bcac6f9db2cb134d3d3c60a21041cde136feb1d9/Documentation/Doxygen/Modules.dox#L37

So as suggested in the cross-referenced comment, it looks like the problem seems to be either the way the command is processed (maybe it needs an extra escaping backslash) by some ITK-internal script prior to being able to generate the corresponding *.dox files from the *.cmake files or the module/group names being inaccurate (e.g. requiring a Module- or Group- prefix).

[dzenanz]

Oh, you have narrowed it down significantly now.

[jhlegarreta]

The First interaction GHA has been intermittently failing since a few days. Unrelated to any patch set that does not alter the workflow script.

[jhlegarreta]

Some more investigation.

The https://github.com/InsightSoftwareConsortium/ITK/pull/3672#issuecomment-1262311304

Importantly enough, I have realized that the \ref command is actually working on *.dox files, e.g. the Geometry Representation Objects section in:

The references in the *.dox files also get translated by Doxygen to a URL having the same pattern as the ones in the *.cmake files: https://insightsoftwareconsortium.github.io/ITKDoxygen/group__Geometry.html vs. https://itk.org/Doxygen/html/group__Group-Numerics.html

Below are two hypotheses following previous comments:

1. On the one hand,

So as suggested in the cross-referenced comment, it looks like the problem seems to be either the way the command is processed (maybe it needs an extra escaping backslash) by some ITK-internal script prior to being able to generate the corresponding *.dox files from the *.cmake files or the module/group names being inaccurate (e.g. requiring a Module- or Group- prefix).

Maybe the references to a module/group within each group (e.g. ITKNarrowBand within the Numerics group) cannot be reached because all ITK (top) modules' (such as Numerics) https://github.com/InsightSoftwareConsortium/ITK/blob/master/CMake/ITKGroups.cmake#L2

identifiers are being prepended with Group-: https://github.com/InsightSoftwareConsortium/ITK/blob/master/CMake/ITKGroups.cmake#L93

And thus, maybe any submodule/subgroup, even if its name is correctly being defined/extracted: https://github.com/InsightSoftwareConsortium/ITK/blob/master/CMake/ITKGroups.cmake#L76

(code snippet added in https://github.com/InsightSoftwareConsortium/ITK/commit/d17fafb3499980cef3b6fd377cc32e85d99b6a27)

e.g. https://github.com/InsightSoftwareConsortium/ITK/blob/master/Modules/Numerics/NarrowBand/itk-module.cmake#L4

cannot be reached because their root is not correctly identified/defined.

2. On the other hand, that Group- prefix was present in a manually-defined primitive *.dox file: https://github.com/InsightSoftwareConsortium/ITK/commit/de5e0bed7b078a90af7ff10ed12b370be9f2ec33#diff-3daa88a1b33eb4ec1358b2844d6befe5189456ce426f2a76127de42c82166d85L16

and was translated into the snippet that is present in the ITKGroups.cmake file on Jul 31, 2011.

At the time of the above commit, the module cross-references did not exist in the ITKGroups.cmake file.

Additionally,** the \ref commands were initially present** when added on Aug 16, 2011, and were additionally escaped: https://github.com/InsightSoftwareConsortium/ITK/commit/43f5de1a5e95f0659a8630583cbe00299cb3b100

But were removed later, on Jan 27, 2018: https://github.com/InsightSoftwareConsortium/ITK/commit/1f4c6e9ece17049fe6725e4884e39984badfa35a

Maybe following the wrong reasoning, trying to fix the autolinks that we are still trying to fix, or maybe some other autolinks. We no longer have access to the gerrit comment mentioned in the above last commit to confirm whether the comment was saying that the group links were not working, or else whether the links were working (Please check whether the modules are still linked.), and the possibly unnecessary \ref commands that might have been mentioned in the comment were referring to autolinks to class, functions and members (which indeed do not need the \ref command, as stated by Doxygen's autolink manual).

So two things to try:

• Try to escape the \refs and see whether this fixes the issue.
• Remove the Group- prefix and see whether this fixes the issue.

[dzenanz]

I do see the comments on gerrit: But they do not answer your question (whether the modules are still linked).

[jhlegarreta]

I do see the comments on gerrit:

Oh, I thought we had lost access to gerrit. Maybe I am unable to see them because my gerrit profile was linked to an email address I no longer have access to.

Thanks for the additional investigation Dženan.

I had another look here: https://github.com/InsightSoftwareConsortium/ITK/blob/1e003467e263d31bfb02589ce2449a413dbe4fa2/CMake/ITKGroups.cmake#L93

And I realize that \defgroup is also escaped. So the best guess is that I need to escape the \ref's I will amend the commit, push force, and we will see if that works.

[dzenanz]

I don't need to be logged in to see the content here: https://review.source.kitware.com/%23/c/23049/

[dzenanz]

Is this ready for merging?

[jhlegarreta]

Is this ready for merging?

It is. Although I cannot guarantee it will fix the issue, it is my best guess.

[jhlegarreta]

• It has not introduced new warnings.
• It has worked for the modules/groups in CMake/ITKGroups.cmake: https://itk.org/Doxygen/html/modules.html:

• I has not worked for each module's description :sob: I think the command requires triple escaping in the itk-module.cmake cmake files. I will propose a PR today/tonight:

Edit: Looks definitely like the tripe escaping was originally there, and I'd dare to say that it was working fine: https://github.com/jhlegarreta/ITK/blame/d929057b5ad07cf2d004afba53b5240eef48334d/Modules/Segmentation/ConnectedComponents/itk-module.cmake The \refs were removed by a wrong assumption of mine related to the Doxygen class autolinking: https://github.com/jhlegarreta/ITK/blame/4b5842f718ef6ca17b8862150ee8bbacf0f725ac/Modules/Segmentation/ConnectedComponents/itk-module.cmake

[jhlegarreta]

I has not worked for each module's description 😭 I think the command requires triple escaping in the itk-module.cmake cmake files. I will propose a PR today/tonight:

Done in PR #3686. Sorry for all the hassle, all caused by an original commit of mine removing the \ref commands and the appropriate escaping.

[jhlegarreta]

PR #3691 also related. Sorry for leaving all these behind and for fixes spanning across multiple PRs 🤦‍♂️ .