Disable TAGFILES in rosdoc2 to separate namespace tf2 documentation in packages

[rkent]

Generated-by: Portions of this commit may include code completion from github.copilot version 1.372.0 or later

Description

This PR modifies Doxygen generation in all packages that define (or extend) the tf namespace by disabling rosdoc2's default import of TAGFILES that it sees. It also modernizes any existing rosdoc2.yaml files to clearly show what has changed from default.

The existence and content of TAGFILES have a significant effect on the documentation generated by rosdoc2. See here for more details.

Within geometry2, here are some examples of the consequences of this:

• In the documentation for tf2, many functions are included that are actually defined in other packages, but without full documentation. See for example Function tf2::eigenToTransform(const Eigen::Affine3d&) which is documented (incompletely) in tf2 here Note the missing details.
• In the documentation for some namespace extension packages such as tf2_eigen, the namespace tf2 is not documented at all. That means that the details of functions such as the above, which are included in the actual .hpp code, are not shown anywhere since they are incorrect in tf2.
• In some cases, the documentation for related packages is leaking into documentation. See for example Function tf2::toMsg(const tf2::Stamped<Eigen::Affine3d>&) in tf2_kdl, where incomplete documentation from tf2_eigen is leaking.

What you see depends on the order that packages are documented in a repository, which is currently uncontrolled. But in any case, the Doxygen-> Breathe/Exhale documentation setup that we use does not handle namespace extensions well.

What this PR does is to preclude each package's documentation from including TAGFILES that were generated by other packages. That way, the tf namespace documentation will be included in each package, with the correct content, regardless of the order of running.

There may be a downside that some cross-package links may not be available, though I could not find any examples of where cross-platform links are working in the current documentation, but not after this PR.

This PR partially addresses #833.

Is this user-facing behavior change?

No, only in documentation

Did you use Generative AI?

See the header

Additional Information

To test this, you will need a recent rosdoc2 from github. After installing rosdoc2 (in a venv), run rosdoc2 twice (to generate then use TAGFILES for all packages). This is easiest done using:

rosdoc2 scan -p <directory containing geometry2>

Without this change, on the second run some of the types of problems mentioned above will appear, though might be slightly different. With these changes, in the first run and any addition runs of rosdoc2, each package should include correct documentation of tf2 classes and functions defined in that package.

[ahcorde]

https://github.com/Mergifyio backport kilted jazzy

[mergify]

backport kilted jazzy

✅ Backports have been created

• #861 Disable TAGFILES in rosdoc2 to separate namespace tf2 documentation in packages (backport #856) has been created for branch kilted but encountered conflicts
• #862 Disable TAGFILES in rosdoc2 to separate namespace tf2 documentation in packages (backport #856) has been created for branch jazzy but encountered conflicts