tf/Reviews/2009-10-07_Doc_Review

Reviewer: Jeremy Leibs

Instructions for doing a doc review

See DocReviewProcess for more instructions

1. Does the documentation define the Users of your Package, i.e. for the expected usages of your Stack, which APIs will users engage with?
2. Are all of these APIs documented?
3. 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?
4. If there are hardware dependencies of the Package, are these documented?
5. Is it clear to an outside user what the roadmap is for the Package?
6. Is it clear to an outside user what the stability is for the Package?
7. Are concepts introduced by the Package well illustrated?
8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
9. Are any mathematical formulas in the Package not covered by papers properly documented?

Jeremy

1. Does the documentation define the Users of your Package, i.e. for the expected usages of your Stack, which APIs will users engage with?
   • Separate Broadcasting Transforms and Receiving transforms users. I would order these differently since the less advanced user is going to want to just listen without broadcasting.
     • TF: reordered and added comments to explain all usage vs extending usage
2. Are all of these APIs documented?
   • The command-line utilities for interacting with tf are undocumented.

     • viewframes and tf_monitor are mentioned. send_transform is mentioned only in doxygen. API for this should be moved out of doxygen, perhaps into a tf/tools subpage along with complete documentation for reset_time, view_frames, tf_monitor, tf_echo, etc.

   • C++ API not clear:
     • Way too many functions in doxygen. Impossible to learn if you don't know what you're looking for.
     • Many of functions are not actually documented.
     • A wiki page would really help with a discussion of mechanism of operation, common code usages.

     • No mention of the fact that the native types worked with by the Transformer are bullet types with appropriate link to bullet documentation. These typedefs without replicated documentation are actually confusing because no documentation actually exists for tf::Transform. You have to read documentation for btTransform (once you find it) and do name replacement on your own.

   • Python API is more clear since there are only 4 functions, could still use some elaboration.
   • In some sense the transform chain representation is an API in and of itself
     • Somewhere I would like a clear diagram of two frames and their relationship as it relates to a Tf message. Essentially I'm looking for direction of the translation and rotations as they relate to parent/child frame. Is transform that of parent in child frame or child in parent frame. This should probably be answered in the FAQ as well.
3. 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?
   • Message filter is missing tutorial.
   • More complicated transform operations is missing a tutorial. I don't need to see a full package-style demonstration tutorial. More of code-snippets on. "How do you transform a point?" "How to you populate a Transform from euler angles?", etc.
4. If there are hardware dependencies of the Package, are these documented?
   • N/A
5. Is it clear to an outside user what the roadmap is for the Package?
   • 0.9 implicit
6. Is it clear to an outside user what the stability is for the Package?
   • 0.9 implicit
7. Are concepts introduced by the Package well illustrated?
   • Not particularly. See discussion of missing APIs above.
     • A diagram and explanation of a simple chain would be very helpful.
     • We cover "What does tf do?" and "How do I use tf?" but we are missing "How does tf work?"
8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
   • Not sure. Is there any research here?
9. Are any mathematical formulas in the Package not covered by papers properly documented?
   • No. Would be nice to have the transform math laid out explcitly somewhere.

For each launch file in a Package

1. Is it clear how to run that launch file?
   • No launch files in package...
2. Does the launch file start up with no errors when run correctly?
3. Do the Nodes in that launch file correctly use ROS_ERROR/ROS_WARN/ROS_INFO logging levels?

Concerns / issues

Jeremy

• Everything mentioned above. In particular I think the tutorials are a good start, but we are still essentially missing "Documentation"
• Small things:
  • Message notifier is mentioned on main page. This is message filter now?
  • Link from CodeAPI is weird page?
  • tf_tutorials I thought used to exist. No mention of or link to this or instructions for where to find a _tutorials package.

Conclusion