joint_trajectory_action/Reviews/2010-01-12_Doc_Review

Reviewer: Tully

See the following: joint_trajectory_action

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

• What does this mean? "The amount of time (in seconds) that the controller is permitted to be late to the goal. " What happens if this is violated? I would never guess this from the name.

  • Explained aborting based on goal_time better

• What are the failure/success conditions? If any constraint is violated what is the behavior? Is there anything besides success and failure?

  • If a constraint is violated, the goal is aborted.

• how quickly does it poll? is there any possibility of it not catching a failure temporarily?

  • It listens to the controller, so approx 100Hz. Everything operates within some margin of error, and this margin is probably fine

• Add the tutorial link at the bottom to the Tutorials page.

  • done

gil

• I understand that the units on goal/trajectory constraints are a somewhat nebulous entity. I still think it would be useful to say something about what .03 or .04 represents, or at least to explain the nebulousness.

  • Explained as units of position, usually radians or meters

• In the beginning of section 3.2 it's stated that the action interface takes a goal of pr2_controllers_msgs/JointTrajectoryGoal. I'm pretty sure that should be pr2_controllers_msgs/JointTrajectoryActionGoal, as it is in the subscribed messages section.

  • The confusion results from the architecture of actions. The goal is of type JointTrajectoryGoal, but the message transmitted over ROS is of type JointTrajectoryActionGoal. I recognize that this is a place for confusion, and I've described what is happening as well as I can, without launching into a lecture on the implementation of actions. If there's something short I can add to diminish confusion, please let me know.

Conclusion