pr2_mechanism/Reviews/2009-11-13_Doc_Review

Reviewer: Wim Meeussen

Instructions for doing a doc review

See DocReviewProcess for more instructions

1. Does the documentation define the Users of the Stack, i.e. for the expected usages of the Stack, which APIs will users engage with?
2. Are all of these APIs documented?
3. Do relevant usages have associated tutorials?

4. Have all Packages in the Stack been API reviewed?

5. Does the Stack conform to the StackDocumentation guidelines?

6. Are there Packages in the Stack that don't belong

Concerns / issues

Wim

• Is the description in the stack.xml informative? This shows up in the summary of the Stack wiki page.

  • No, the summary is non-existent. --> DONE (fixed in manifest)

• For the expected usages of your Stack, are the necessary APIs documented? (in other words, internal APIs do not need to be documented, some justification needs to be provided by the component owner as to what is/isn't internal)

  • Writing joint controllers: OK: JointState c++ api documented, controller interface c++ api documented, controller manager ros api documented.

  • Writing cartesian controllers: OK: Chain c++ api documented, urdf::Model api documented in [[urdf] package.
• Do relevant usages have associated tutorials?

  • Yes, although they live in the controllers/Tutorials, but are linked to from the pr2_mechanism/Tutorials

• Have all Packages in the Stack been API reviewed?

  • All except for pr2_hardware_interface

• Is the documentation for these APIs correct? Look for typos, things that are out-of-date, ambiguities, omissions, etc...
  • This has been checked in the doc review and user testing.

• Does the Stack conform to the StackDocumentation guidelines?

  • Summary of stack. Should summarize what functionality a stack exports and at what level (i.e. C++ library, scripts, ROS nodes, etc...): Not there. --> DONE (fixed in manifest)

• Are there Packages in your Stack that don't belong
  • Not any more.

Conclusion