fingertip_pressure/Reviews/Jan_12_2010_Doc_Review

Reviewer:

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?

Sure, anyone who wants to use the fingertip sensors on the PR2.

1. Are all of these APIs documented?

Looks like it.

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

Nope. A tutorial would really be nice.

1. If there are hardware dependencies of the Package, are these documented?

Well, it's obvious that the fingertip sensors are hardware dependencies. Hopefully an explanation of the hardware will go in the PR2 manual.

1. Is it clear to an outside user what the roadmap is for the Package?

roadmap?

1. Is it clear to an outside user what the stability is for the Package?

"This package has not been reviewed so its API should be considered unstable." Pretty clear to me.

1. Are concepts introduced by the Package well illustrated?

Not really. A snapshot of the Fingertip Sensors visualization panel like this one:

• 

alongside a picture of the fingertip sensors, with the appropriate sensor numbers labeled as front, right side, left side, tip, and back (and correspondences obvious on the picture of the fingertip sensors) should really be somewhere prominent, like on the package summary page. Perhaps along with a picture of the relevant tf frame, snapshot from rviz. Or at least instructions on how to view the relevant tf frame in rviz.

• Added the picture of the panel, thanks. I don't have the other suggested pictures on hand; they can be added later.

1. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?

N/A

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

Perhaps this could be in a brief tutorial? Also, the launch files are in 'demo', rather than the more usual 'launch', which is confusing.

• Renamed demo to launch on trunk.

1. Does the launch file start up with no errors when run correctly?

doing 'roslaunch fingertip_demo.launch' results in the following error message:

while processing /u/hsiao/ros/pkgs/pr2_ethercat_drivers/fingertip_pressure/demo/fingertip_demo_no_sim.launch: <node> tag is missing required attribute: name. Node xml is <node output="screen" pkg="fingertip_pressure" respawn="false" type="sensor_info.py"/>

• Fixed launch file in trunk by adding name attributes to all node tags.

1. Do the Nodes in that launch file correctly use ROS_ERROR/ROS_WARN/ROS_INFO logging levels?

Not sure

Concerns / issues

1. (Caroline) This sentence: "calibration data on the data such as scaling factors, zero points and reference frames." doesn't really make sense.

   • Fixed.

2. (Caroline) Due to my general dislike of doxygen, I think that most of the information in the code API should be on the package page. Especially the ROS API and the diagram. Most users try to avoid looking at the code API if at all possible.

   • Fixed.

(KJ) fingertip_pressure is misspelled (fintertip_pressure) in the Package Summary

• Fixed in the manifest on trunk (will take a while to propagate to the wiki).

(KJ) Strongly agree with Caroline on the info in the code API going on the package page. I've used this package and it took me awhile to find the nice diagram in the code API.

• Fixed.

Conclusion