image_transport/Reviews/9-30-09_Doc_Review

Reviewer: Ethan Dreyfuss

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?
   1. Yes, people who want to send images using specialized transport strategies.
2. Are all of these APIs documented?
   1. Yes.
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?
   1. Yes, there are tutorials which are indexed and seem to have good coverage. Two are currently in progress and have not been reviewed:
      1. Managing Transport Plugins
      2. Writing a New Transport.

   2. In the Writing a Simple Image Publisher plugin the example didn't include <ros/ros.h> directly. This seems like good practice, so I added it. If you disagree with this change please revert it, if you agree please make the corresponding change to Writing a Simple Image Subscriber.

   3. I like that the tutorials include creating a sandbox package and editing CMakeLists.txt and such, I think this is a very good style since there isn't much extra text and it is easily skipped over by experienced users but can help seriously unblock novice users.
4. If there are hardware dependencies of the Package, are these documented?
   1. No hardware dependencies.
5. Is it clear to an outside user what the roadmap is for the Package?
   1. No, though I'm not sure one is really needed. The only major thing I can think of that people might be wondering about with regards to the roadmap is non-C++ support. *EDIT* I see that this is actually present in the stack roadmap.
6. Is it clear to an outside user what the stability is for the Package?
   1. No, but I'm not sure it is required.
7. Are concepts introduced by the Package well illustrated?
   1. Yes, but for the multi-transport option it would be useful to have a simple example of how to configure this setup using transport hints.
   2. Also for the two examples in the Nodes section it would be useful to format them in such a way that it is clear that they are two separate examples.
8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
   1. N/A
9. Are any mathematical formulas in the Package not covered by papers properly documented?
   1. N/A

For each launch file in a Package

N/A

1. Is it clear how to run that launch file?
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

1. There should probably be an index page somewhere fairly obvious that lists known image transport plugins and links to the associated documentation.

Conclusion

1. A few minor issues to clean up, but overall the documentation is in very good shape.