Parsing metadata

[bkueng]

I'm working on PX4, which used genmsg for code generation. Now the ask has come up to generate docs for .msg files, and I see ROS uses http://wiki.ros.org/rosdoc_lite, which parses the files independently, w/o any structure for metadata (comments in particular). This has obviously some drawbacks:

• It's very limited in how you can render docs
• Fields/msgs are not required to be documented at all
• Missing mechanism for additional metadata (e.g. minimum value for a field)

I'm suggesting to bring more structure to comments and parse them with genmsg, which then can be used to generate docs as well (single parser for all use-cases). I have not gone into the details, but I imagine something like this:

# topic description
# @namespace xy

# field description
# @min min-value
# @ignored-value NaN
float x

float y # existing single-line field+comment is allowed as well

The tags are then parsed generically (no tag implies @comment tag), which then gets added as a dict to genmsg.MsgSpec and genmsg.Field, so they can be used in a template. This should fit into the existing .msg file format structure.

Is there interest in extending files into that direction, and if so, are there any specific requirements you'd like to see?

@dirk-thomas @tfoote

[dirk-thomas]

@bkueng sorry, I am not a maintainer of this repository anymore.

[tfoote]

@bkueng We would definitely consider a proposal to extend the msg format to be able to add richer documentation. This repository is entirely focused on ROS 1's implementation and with the final ROS 1 distro already released this is basically in maintenance only mode.

This sort of proposal will want a much larger viewing audience as well as look forward for ROS 2. To that end I'd suggest that you propose this on ROS Discourse in the Next Generation ROS category: https://discourse.ros.org/c/ng-ros/25 and we can look at extending this for upcoming distributions.

[tfoote]

There's also some active ongoing work relating to this right now such as: https://github.com/ros2/rosidl/pull/593 I'm going to close this in favor of continuing the discussion elsewhere either discourse or on rosidl