Move \author tags to \file \brief (backport #870)

[mergify]

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

Description

This is a somewhat subtle (and optional) PR. You won't break my heart if you decide it is not worth the effort.

There are two related issues here.

1. There are many Doxygen tags in this repo of the form:

/** \author Tully Foote */

appearing right after the license boilerplate. The problem is that these are interpreted as being applied to the namespace, whose definition starts soon afterwards. The original intention, I am reasonably sure, is to apply to the file, not the namespace.

2. The sphinx/exhale code being use to generate current documentation does not actually support the \author tag (though this is valid in Doxygen.)

The result is that, currently, this generates a section in the Namespace that looks like this:

---

Namespace tf2

...

Detailed Description

Tully Foote

---

After this PR, the author entry no longer appears in the Namespace section. Instead, it appears under the File section, like this:

---

File buffer_core.hpp

...
Author: Tully Foote.

---

The downside (other than the effort to do this PR at all) is that in the Doxygen output, the author tag does not appear even though it could. But we do not display the Doxygen result by default.

Is this user-facing behavior change?

No, it only affects documentation.

Did you use Generative AI?

See the header.

---

This is an automatic backport of pull request #870 done by [Mergify](https://mergify.com).

[ahcorde]

Pulls: #875
Gist: https://gist.githubusercontent.com/ahcorde/f9bd620bbe7f84264a80863ae5bf3f33/raw/667e2d175d0e16bbd20f84d1957acdbaf5b436aa/ros2.repos
BUILD args: --packages-above-and-dependencies test_tf2 tf2 tf2_bullet tf2_geometry_msgs tf2_kdl tf2_ros
TEST args: --packages-above test_tf2 tf2 tf2_bullet tf2_geometry_msgs tf2_kdl tf2_ros
ROS Distro: kilted
Job: ci_launcher
ci_launcher ran: https://ci.ros2.org/job/ci_launcher/17746

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