Fix various documentation errors in tf2 (backport #857)

[mergify]

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

Description

This PR fixes various issues causing errors in the rosdoc2 documentation of tf2. Most are just fixes around individual function documentations.

Probably the most important change is in tf2/Doxyfile. Without this, the widely-used Vector3 class is not being documented, and references to its use cause complaints.

Although this PR does not depend on #856, I recommend that you land that first to get consistent rosdoc2 results.

This PR partially addresses #833

Is this user-facing behavior change?

This only affects documentation generation by rosdoc2

Did you use Generative AI?

See the header.

Additional information.

Two errors remain in documentation. One is a complaint about None as a language, which will be fixed in a pending PR to redo the conf.py files. The other is:

/home/kent/github/rkent/rosdoc2/docs_build/tf2/tf2/wrapped_sphinx_directory/generated/classtf2_1_1impl_1_1Converter.rst:13: WARNING: Duplicate C++ declaration, also defined at generated/classtf2_1_1impl_1_1Converter:13.
Declaration is '.. cpp:function:: inline void convert (const A &a, B &b)'. [duplicate_declaration.cpp]
/home/kent/github/rkent/rosdoc2/docs_build/tf2/tf2/wrapped_sphinx_directory/generated/classtf2_1_1impl_1_1Converter.rst:13: WARNING: Duplicate C++ declaration, also defined at generated/classtf2_1_1impl_1_1Converter:13.
Declaration is '.. cpp:function:: inline void convert (const A &a, B &b)'. [duplicate_declaration.cpp]
/home/kent/github/rkent/rosdoc2/docs_build/tf2/tf2/wrapped_sphinx_directory/generated/classtf2_1_1impl_1_1Converter.rst:13: WARNING: Duplicate C++ declaration, also defined at generated/classtf2_1_1impl_1_1Converter:13.
Declaration is '.. cpp:function:: inline void convert (const A &a, B &b)'. [duplicate_declaration.cpp]

This comes from tf2/include/tf2/impl/convert.hpp and the declarations like:

template< >
template<typename A, typename B>
inline void Converter<true, true>::convert(const A & a, B & b);

template< >
template<typename A, typename B>
inline void Converter<true, false>::convert(const A & a, B & b)

rosdoc2 document generation does not appear to be able to detect Converter<true, true> and Converter<true, false> as separate function types. I have not been able to devise a fix for this.

---

This is an automatic backport of pull request #857 done by Mergify.

[mergify]

Cherry-pick of 054b809 has failed:

On branch mergify/bp/jazzy/pr-857
Your branch is up to date with 'origin/jazzy'.

You are currently cherry-picking commit 054b809.
  (fix conflicts and run "git cherry-pick --continue")
  (use "git cherry-pick --skip" to skip this patch)
  (use "git cherry-pick --abort" to cancel the cherry-pick operation)

Changes to be committed:
	modified:   tf2/include/tf2/LinearMath/Matrix3x3.hpp
	modified:   tf2/include/tf2/LinearMath/Vector3.hpp
	modified:   tf2/include/tf2/buffer_core.hpp
	modified:   tf2/include/tf2/convert.hpp

Unmerged paths:
  (use "git add/rm <file>..." as appropriate to mark resolution)
	both modified:   tf2/Doxyfile
	deleted by us:   tf2/doc/cpp_api_docs.rst

To fix up this pull request, you can check it out locally. See documentation: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally

[ahcorde]

Pulls: #864
Gist: https://gist.githubusercontent.com/ahcorde/98ee81a1a8baa13de2fbabdebd4b6909/raw/6570e39cc87ed270fb4c8c235f4d71052bd54a39/ros2.repos
BUILD args: --packages-above-and-dependencies tf2
TEST args: --packages-above tf2
ROS Distro: jazzy
Job: ci_launcher
ci_launcher ran: https://ci.ros2.org/job/ci_launcher/17620

• Linux
• Linux-aarch64
• Linux-rhel
• Windows