Reviewer: Tully Foote
Instructions for doing a doc review
See DocReviewProcess for more instructions
- Does the documentation define the Users of your Package, i.e. for the expected usages of your Stack, which APIs will users engage with?
- Are all of these APIs documented?
- Do relevant usages have associated tutorials? (you can ignore this if a Stack-level tutorial covers the relevant usage), and are the indexed in the right places?
- If there are hardware dependencies of the Package, are these documented?
- Is it clear to an outside user what the roadmap is for the Package?
- Is it clear to an outside user what the stability is for the Package?
- Are concepts introduced by the Package well illustrated?
- Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
- Are any mathematical formulas in the Package not covered by papers properly documented?
For each launch file in a Package
- Is it clear how to run that launch file?
- Does the launch file start up with no errors when run correctly?
- Do the Nodes in that launch file correctly use ROS_ERROR/ROS_WARN/ROS_INFO logging levels?
Concerns / issues
- All messages are documented in the msg file.
- The summary is accurate.
- Tutorials links to tf package.
- Troubleshooting links to trac
Nit-picky detail. I don't like the "This expresses" usage in the message docs. It is inconsistant across messages. I much prefer the "A representation of _____" phrasing.
- For example, in Wrench I would rather see: "A representation of force in free space, separated into linear and angular parts."
r24763 I would like a pointer from TransformStamped to the the appropriate tf documentation.
(ticketed into geometry stack https://code.ros.org/trac/ros-pkg/ticket/3008) On several messages, a pointer to good reference on fixed-axis representation would be nice.
- A possibility would be a section on the main page for: definitions of terms and conventions. I don't think it has to be fully flushed out yet, but it would serve as a place to start putting that information when they needed it.
(added to common_msgs)A short description and links as appropriate to an explanation of ROS messages, the the goal of having message-only packages to serve as a means of allowing nodes to interact without compilation dependenciees would be great, but probably unnecessary.