Fix up documentation build for rmw when using rosdoc2

[hidmic]

Precisely what the title says. This patch:

• Substitutes trailing [] tokens for leading * tokens for pointer argument types.
• Normalizes type naming to preclude duplication warnings.
• Handles RCUTILS_DEPRECATED_WITH_MSG() macros
• Handles RMW_PUBLIC_TYPE macros.
• De-duplicates some declarations.

[hidmic]

Full CI!

• Linux
• Linux-aarch64
• macOS
• Windows

Argh, build issues in rmw_connextdds_cpp...

[hidmic]

Alright, it wasn't just rmw_connextdds_cpp.

Re-running full CI:

• Linux
• Linux-aarch64
• macOS
• Windows

[ivanpauno]

De-duplicates some declarations.

Is there a way to make doxygen ignore that instead of renaming *_t to *_s.
I don't mind much, but it seems a bit unnecessary to break API that way.
Though, I think we're never using struct *_t in code and always *_t directly.

[hidmic]

Is there a way to make doxygen ignore that instead of renaming *_t to *_s.

I followed ros2/rcutils#333 precedent here, but perhaps \cond based suppression of typedefs is possible e.g.:

/// \cond flag
typedef
/// \endcond
struct type_name_t {

}
/// \cond flag
type_name_t
/// \endcond
;

Though I do find duplicate type definitions awkward albeit legal.

Though, I think we're never using struct *_t in code and always *_t directly.

Well, I've found some cases. Specially in rcl. Definitely not a policy. More like an easter egg I'd say.

[ivanpauno]

I followed ros2/rcutils#333 precedent here, but perhaps \cond based suppression of typedefs is possible e.g.:

That seems to be enough precedent, we will have to bump the major number next release.

[clalancette]

This all looks really good to me with green CI.

Thanks for iterating!

[wjwwood]

Why this change? (just curious)

[hidmic]

WARNING: doxygenfunction: Unable to resolve function "rmw_topic_endpoint_info_set_gid" with arguments (rmw_topic_endpoint_info_t*, const uint8_t, size_t) in doxygen xml output for project "rmw Doxygen Project" from directory: ...
Potential matches:

• rmw_ret_t rmw_topic_endpoint_info_set_gid(rmw_topic_endpoint_info_t *topic_endpoint_info, const uint8_t gid[], size_t size)

It appears exhale (i.e. the thing that turns Doxygen XML into Sphinx compliant ReST) fails to pick up a trailing [] as a type modifier. I haven't dug into it deep enough to find out why.

[wjwwood]

Will this break rmw implementations?

[clalancette]

Any RMW implementation that was using a "bare" rmw_event_type_t before should be fine; we are still defining that as part of the typedef. If an RMW implementation was using enum rmw_event_type_t, then it would now be broken.

I don't think we have any users of that in the core, but I will request a full CI run before we merge this. There might be third-party ones that use enum rmw_event_type_t, so I think a release note is in order for this change.

[hidmic]

Re-running full CI:

• Linux
• Linux-aarch64
• macOS
• Windows

[hidmic]

Alright, all green !

[ros-discourse]

This pull request has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/ros-2-tsc-meeting-minutes-2021-9-16/22372/1