URDF
Reviewer: bhaskara
Instructions for doing a doc review
See DocReviewProcess for more instructions
- Does the documentation define the Users of your Package, i.e. for the expected usages of your Stack, which APIs will users engage with?
- Are all of these APIs documented?
- 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?
- If there are hardware dependencies of the Package, are these documented?
- Is it clear to an outside user what the roadmap is for the Package?
- Is it clear to an outside user what the stability is for the Package?
- Are concepts introduced by the Package well illustrated?
- Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
- Are any mathematical formulas in the Package not covered by papers properly documented?
For each launch file in a Package
- Is it clear how to run that launch file?
- Does the launch file start up with no errors when run correctly?
- Do the Nodes in that launch file correctly use ROS_ERROR/ROS_WARN/ROS_INFO logging levels?
Concerns / issues
Bhaskara
Wim
- Fix spelling mistake in manifest
- Stability and roadmap
- Finish the tutorials
- Possibility of having command line validator
- Possibly change name of subsection in Tutorials list for pr2 tutorials
Bhaskara
- Go over urdf spec
Wim
Fixed:
- fixed in trunk
- fixed in trunk
- The first tutorial is there. Could you take a look at it?
- fixed in trunk
- fixed in wiki
Todo:
- Add second tutorial.
Bhaskara
I went over the urdf spec and fixed some minor typos. Overall, I found it fairly thorough and understandable. Comments:
- Not all optional parameters describe what default value is (e.g., joint/calibration).
- 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.
- The gazebo elements section is not done. This seems more necessary.
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.