rosdep/Reviews/2010-01-12_Doc_Review

Reviewer: Nate

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
2. Are all of these APIs documented?
   • Yes
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?
   • Yes
4. If there are hardware dependencies of the Package, are these documented?
   • N/A
5. Is it clear to an outside user what the roadmap is for the Package?
   • No
6. Is it clear to an outside user what the stability is for the Package?
   • No
7. Are concepts introduced by the Package well illustrated?
   • Almost, see concerns below.
8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
   • N/A
9. Are any mathematical formulas in the Package not covered by papers properly documented?
   • N/A

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

Notes from Nate

1. Package Summary:

   1. The phrase "system dependencies" is ambiguous. Maybe say something like "ROS dependencies" or "ros package dependencies". The text in the first paragraph of the Code API documentation could be used here.

      • Tully : Promoted to manifest

2. Tutorials:

   1. The term "rosdep.yaml" is introduced here, where it has previously been referred to as the "Mapping File". It might be good to be consistent, and use the latter phrase on this page. On the "Mapping File" page, the actual filename can be introduced.

      • Tully : All references changed to rosdep.yaml as discussed in previous reviews.

   2. The Add Support for an OS to rosdep tutorial could use more explanation. The code is there, but some text describing how it works would be helpful.

3. Code API

   1. The Usage section has different instructions than the main page.

      • Tully : Changed to note code API unstable.

Notes from Melonee

1. Tutorials:

   1. How to add a system dependency to a package

      • there is a broken link: rosdep definitions

      • Tully : Gone

   2. All tutorials: More descriptions for the large blocks of code in the tutorials.

      • Tully : Added comments CodeRef not working?

2. Code API

   1. The instructions on the main page need to be updated to reflect the wiki.

      • Tully : Changed to note code API unstable.

Conclusion