roscpp/Reviews/2010-01-13_Doc_Review

Reviewer: Radu

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?

   • Yes. ROSCpp is the cornerstone of any C++ package that wants to interface with ROS.

2. Are all of these APIs documented?

   • Yes, and it seems that roscpp has already undergone a few API reviews. In terms of API documentation, there are a few small bits (I mean really small!) that we could improve I suppose, but I am not sure whether this needs to be done now or later:

   • missing class descriptions (e.g., see doc/api/roscpp/html/annotated.html)

     • Josh: A lot of these are internal and not for public consumption. We really need a way of removing those from the doxygen. There were some that are public that didn't have briefs though. I've updated those. FIXED

   • excellent job on providing usage example in the documentation (!!!) for most methods, but it would be awesome if we could cover all under some classes at least. I know that it's a pain, but they look so pretty and they are quite useful. See doc/api/roscpp/html/classros_1_1NodeHandle.html for example.

     • Josh: If there are specific calls you think need them in the doxygen docs we can probably add them. For the most part though usage docs are now going on the wiki (hence the overview)

   • maybe unrelated, but roscpp_tutorials (doc/api/roscpp_tutorials/html/index.html) would need a front page with some basic description and a list of the tutorials in there? I only bring this up since it links from doc/api/roscpp/html/.

     • Josh: I changed the link to point to the wiki page. FIXED.
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?

   • Yup. The tutorials cover basic publishing/subscribing, parameters, etc. I did not check them to see if the instructions given are correct, but talking to a few people that just started out, it appears that they do the right thing. Maybe a small thing again, it feels a bit weird to have 5 basic tutorials and 1 intermediate. I would also link http://wiki/roscpp/Overview/Time back to http://wiki/roscpp_tutorials/Tutorials/Timers, because it's super useful (there's already a link vice versa).

   • Josh: I assume you mean the roscpp/Overview/Timers page, not roscpp/Overview/Time? If so, FIXED

4. If there are hardware dependencies of the Package, are these documented?

   • No hardware dependencies.

5. Is it clear to an outside user what the roadmap is for the Package?

   • Yes.

6. Is it clear to an outside user what the stability is for the Package?

   • Yes. The status is API cleared.

7. Are concepts introduced by the Package well illustrated?

   • Yes, though again a small thing... we're linking pages from the old wiki in some cases such as http://pr.willowgarage.com/wiki/ROS/Tutorials from doc/api/roscpp/html/. It would be nicer to have those under ros.org, but again, this might not be important at all for now.

   • Josh: FIXED
8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?

   • Not relevant.

9. Are any mathematical formulas in the Package not covered by papers properly documented?

   • Not relevant.

For each launch file in a Package

1. Is it clear how to run that launch file?

   • Not relevant.

2. Does the launch file start up with no errors when run correctly?

   • Not relevant.

3. Do the Nodes in that launch file correctly use ROS_ERROR/ROS_WARN/ROS_INFO logging levels?

   • Not relevant.

Concerns / issues

All expressed above.

[There's one thing that I would like to see as a user, but I am not sure what's the best form of doing that now... and that is some pictures/graphs in the http://wiki/roscpp/Overview section, or maybe the roscpp tutorials? There are a couple of small graphs that we always use in ROS slides, such as the talker example. I just feel that placing a few of those in web pages later on, might improve the whole thing. But maybe that's just me.. I like pictures more :). All I'm saying is that whatever we use in slides, we could definitely finetune for the web as well, to balance the large amount of text in there.]

• Josh: What kinds of pictures/graphs? I don't think this is necessarily in scope for M3 (especially since we have plenty of them in the other ROS tutorials), but I can look into it.

Conclusion

Great job overall. I think everything is well covered for a first release. Not sure if we want to address any of the small issues I wrote above now (or never), but it would be nice.