roslib/Reviews/2010-01-12_Doc_Review

Reviewer: Brian

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. Is it clear to an outside user what the roadmap is for the Package?
5. Is it clear to an outside user what the stability is for the Package?
6. Are concepts introduced by the Package well illustrated?

Concerns / issues

• No comments in Time or Clock messages.
  • kwc: FIXED
• Having both Time and Clock is confusing; should Time be marked (perhaps in comments) as being deprecated?
  • kwc: FIXED in comments

• Docs say "use rospy," but every rospy program starts with import roslib; roslib.load_manifest(). Perhaps that exception should be noted.

  • kwc: FIXED
• No class/module summary in Python API docs for:
  • roslib.message
  • roslib.os_detect
  • roslib.packages
    • kwc: FIXED
• C++ API docs:

  • Link for "client implementations" from http://www.ros.org/doc/api/roslib/html/c++/ points to a stale part of the pr wiki: http://pr.willowgarage.com/wiki/ROS/client_libs. The link should be fixed, and the stale page (and all others like it) should be removed.

    • jfaust: FIXED

  • When it's not meant to refer to the namespace, roslib should be prefixed with % to prevent Doxygen from making it a link.

  • In reference to roslib's messages: "In some cases it is possible to add fields to these messages, but you must do so with great care." Do we even want to say that?
    • jfaust: Ken FIXED
  • Why is gendeps documentation in the C++ API? Seems like it belongs in the wiki.
    • jfaust: Ken GONE
  • genmsg.py and gensrv.py (also documented in the C++ API) are no longer used by the build system and can be removed
    • jfaust: Ken FIXED

  • The class list page is confusing: http://www.ros.org/doc/api/roslib/html/c++/annotated.html.

    • Most of the classes don't have summaries (an artifact of the message generator, perhaps?)
      • jfaust: All but the generated messages now have summaries
    • What's the difference between roslib::Time and ros::Time?
      • jfaust: roslib::Time is the message
    • Can the *Base classes be marked "don't use me"?
      • jfaust: FIXED
    • Perhaps there should be a link into the roscpp overview, where time is explained with better context.
      • jfaust: FIXED

Conclusion