search

ros-infrastructure / rosdoc2

Command-line tool for generating documentation for ROS 2 packages.
Apache License 2.0
29 stars 9 forks source link

Trailing double under-scores produces `Anonymous hyperlink mismatch` warning #29

Closed aprotyas closed 2 years ago

aprotyas commented 2 years ago

This issue is mostly seen with macros (such as RCPPUTILS_THREAD_ANNOTATION_ATTRIBUTE__), since they tend to have trailing double under-scores. The warning reads:

line : Error: Anonymous hyperlink mismatch: 1 references but 0 targets.
See "backrefs" attribute for IDs.

The problem here is that exhale takes identifiers verbatim and throws them into their respective .rst files, and double under-scores is used for anonymous hyperlinking in the restructured text format.

The immediate solution is to exclude these identifiers in Doxygen, but I'm opening this issue to track progress on a real fix.

clalancette commented 2 years ago

We should rename RCPPUTILS_THREAD_ANNOTATION_ATTRIBUTE__ to something like RCPPUTILS_THREAD_ANNOTATION_ATTRIBUTE_IMPL. That is standards compliant, and also fixes this particular issue. Then we can also get rid of the @cond that we are currently using.

aprotyas commented 2 years ago

Okay, since symbols with double underscores are not standards compliant anyway, I believe this is not a cause for concern anymore.

Feel free to close this issue.

We should rename RCPPUTILS_THREAD_ANNOTATION_ATTRIBUTE__ to something like RCPPUTILS_THREAD_ANNOTATION_ATTRIBUTE_IMPL. That is standards compliant, and also fixes this particular issue. Then we can also get rid of the @cond that we are currently using.

Should I open an issue in rcpputils? I don't think you can transfer across orgs.

clalancette commented 2 years ago

Should I open an issue in rcpputils? I don't think you can transfer across orgs.

Yeah, I think that makes sense. I'll close this one and let you open a new one in rcpputils.