URDF

Reviewer: bhaskara

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

Bhaskara

Wim

1. Fix spelling mistake in manifest
2. Stability and roadmap
3. Finish the tutorials
4. Possibility of having command line validator
5. Possibly change name of subsection in Tutorials list for pr2 tutorials

Bhaskara

1. Go over urdf spec

Wim

Fixed:

1. fixed in trunk
2. fixed in trunk
3. The first tutorial is there. Could you take a look at it?
4. fixed in trunk
5. fixed in wiki

Todo:

1. Add second tutorial.

Bhaskara

I went over the urdf spec and fixed some minor typos. Overall, I found it fairly thorough and understandable. Comments:

1. Not all optional parameters describe what default value is (e.g., joint/calibration).
2. Some of the concepts (e.g. safety limits) have links to detailed explanations while others don't. I don't think this is a requirement for the current release though, just something worth adding over time.
3. The gazebo elements section is not done. This seems more necessary.

4. It might be worth writing an XML DTD (http://www.w3schools.com/dtd/dtd_intro.asp) for the URDF language, and linking to that on the wiki. That would also allow automatic validation.

Bhaskara

Tutorial 1 looks good to me. Dynamics info is one thing that might be worth adding.

Also, I added a mention of urdf_check to the front page as it seems like a part of the API.

Wim

Great! I added the second tutorial. For now that tutorial is limited to create the urdf model and initialize it, but later I would like it to cover walking through the urdf. But that's outside the scope of this review.

Conclusion