Better documentation needed for Joint::GetAngle()

[osrf-migration]

Original report (archived issue) by Jonathan Bohren (Bitbucket: jbohren).

---

So, physics::Joint::GetAngle() returns different quantities for different types of joints, and if one burrowed down into the documentation from the respective libraries, one would arrive at the following conclusions:

• revolute: The joint angle in the range -pi to pi
• gearbox: The joint angle in the range -pi to pi
• revolute2: The joint angle in the range -pi to pi
• prismatic: The joint's linear position
• ball: (not implemented) (returns Zero)
• universal: One of the joint's angles in the range -pi to pi
• piston: ???

But Gazebo patches these libraries to handle unwrapped angles in some cases. Where is the best place to document this behavior, in each joint class's implementation? If it goes there then it might not be visible to someone trying to understand the API. Should it just go in the Joint base class?

[osrf-migration]

Original comment by Jonathan Bohren (Bitbucket: jbohren).

---

• Edited issue description

[osrf-migration]

Original comment by Steve Peters (Bitbucket: Steven Peters, GitHub: scpeters).

---

The intended goal for the revolute joint is an unwrapped angle. Our patched version of ODE supports this, as well as simbody and dart. Bullet doesn't currently support it (hence #1074 and the angle wrapping test in joint_revolute.cc).

The universal joint is also wrapped (#724), which which we had to work around during the VRC.

We're currently in the process of adding integration tests to verify joint behavior.

Regarding documentation, we should probably annotate GetAngle for each joint type to indicate what it returns.

[osrf-migration]

Original comment by Jonathan Bohren (Bitbucket: jbohren).

---

Awesome, thanks for the feedback!