[Documentation] [TitleIndex] [WordIndex

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?
  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?
  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.]

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.


2019-12-07 13:03