xacro/Reviews/2009-10-06_Doc_Review

Reviewer: Tully Foote

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. If there are hardware dependencies of the Package, are these documented?
5. Is it clear to an outside user what the roadmap is for the Package?
6. Is it clear to an outside user what the stability is for the Package?
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?
9. Are any mathematical formulas in the Package not covered by papers properly documented?

For each launch file in a Package

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

Tully

• No users/use case at top.

  • Tully Added

• Code API link goes to a blank page. It should just redirect back to the wiki since there's no good content in doxygen.

  • Tully Added link to wiki from new doxygen mainpage.dox

• How does chaining of macros work?

  • Stu Gave an example of chaining, and stated the order of expansion

• Are there any features planned for the future? This should be noted in manifest.

  • Stu Not currently

• Is the parameter fields white space sensitive?

  • Stu fixed.

• Can a parameter be mixed with math expressions?

  • Stu Yes, and that's stated and shown in an example. What would make it more clear?

• What are the supported rospack commands?

  • Stu Linked to roslaunch, which has the list

Conclusion