Reorder inclusion of extra_doxyfile_statements so we can override rosdoc2_doxyfile_statements #210
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…doc2_doxyfile_statements Signed-off-by: R Kent James <[email protected]> Generated-by: Portions of this commit may include code completion from github.copilot version 1.372.0 or later
tfoote
approved these changes
Nov 20, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Generated-by: Portions of this commit may include code completion from github.copilot version 1.372.0 or later
This issue is briefly discussed in #204 but let me try to elaborate.
It turns out that the included TAGFILES can have a significant effect on what is or is not documented by Doxygen, and by implication the breathe/exhale documentation that we use. This is particularly sensitive to Namespace. What TAGFILES are included, and how and whether that namespace is documented in various packages, can affect whether you see: 1) only the new functions and methods in a namespace in a package, or 2) nothing in the namespace, or 3) the entire namespace (albeit with broken documentation) including from other packages. All TAGFILES currently seen by rosdoc2 are currently included, which depends on the uncontrolled order that packages are built.
geometry2, with its shared namespace definitions for tf2, suffers somewhat from this. Example: in tf2, you have Function tf2::fromMsg(const geometry_msgs::msg::Pose&, Eigen::Affine3d&) as well as in tf2 eigen as Function tf2::fromMsg(const geometry_msgs::msg::Pose&, Eigen::Affine3d&) But the one in tf2 is partly broken without the details, while the one in tf2_eigen is correct. Perhaps a worse problem is that the documentation of namespace tf2 in tf2_eigen includes all of the functions defined in tf2, but with broken definitions.
There are a few fixes I have planned to address this, but ultimately I need to be able to disable automatic usage of found TAGFILES in packages. The current design of rosdoc2 prevents this, as though you can add extra doxyfile statements, they get overridden by the generated statements.
This PR simple reverses the order, so that extra_doxyfile_statements can override the defaults. extra_doxyfile_statements is a very rarely used feature, so I doubt this will affect anyone.