imu_drivers/Reviews/Jan 11 2010_Doc_Review

Reviewer:

• Jeremy Leibs

Instructions for doing a doc review

See DocReviewProcess for more instructions

1. Does the documentation define the Users of the Stack, i.e. for the expected usages of the Stack, which APIs will users engage with?
2. Are all of these APIs documented?
3. Do relevant usages have associated tutorials?

4. Have all Packages in the Stack been API reviewed?

5. Does the Stack conform to the StackDocumentation guidelines?

6. Are there Packages in the Stack that don't belong

Jeremy

1. Does the documentation define the Users of the Stack, i.e. for the expected usages of the Stack, which APIs will users engage with?
   • Not formally, but implicitly anyone that wants to use an IMU.
   • Implies Wiimote-support. Will this be in released stack or not? Level of support unclear at stack page. Also confusing because mentioned in stack despite belonging to joystick_drivers.
   • A little more discussion of the generic IMU API would be useful.
2. Are all of these APIs documented?
   • Describes a consistent minimal API that imu nodes should follow to be usable as an imu. Could use a little more of an explanation about the details of this API.
3. Do relevant usages have associated tutorials?
   • N/A at stack-level

4. Have all Packages in the Stack been API reviewed?

   • microstrain_3dmgx2_imu - Yes
   • wiimote - Not API reviewed, marked as unstable on wiimote page, but not on stack page.

5. Does the Stack conform to the StackDocumentation guidelines?

   • Summary is very brief (probably ok)
   • Links to usages would be good, but only if there is an appropriate example package.
6. Are there Packages in the Stack that don't belong
   • No

Wim

1. What is the behavior of the imu/calibrate service. Does it lock up until calibration is completed? It would be good to explain the ros api components in more detail.
2. Does the documentation define the Users of the Stack, i.e. for the expected usages of the Stack, which APIs will users engage with?
   • The introduction is a little brief; it could be good to explain the goal/users of the stack a little more. E.g. are the drivers to be used in kernel/library/rosnode?
3. Are all of these APIs documented?
   • What is the behavior of the imu/calibrate service. Does it lock up until calibration is completed? It would be good to explain the ros api components in more detail.
4. Do relevant usages have associated tutorials?
   • the tutorial brings up the imu with zero covariance, which is not valid. I would either change the default values for the covariance, or set a covariance in the tutorial.

5. Have all Packages in the Stack been API reviewed?

   • Yes

6. Does the Stack conform to the StackDocumentation guidelines?

   • Yes
7. Are there Packages in the Stack that don't belong
   • No

Concerns / issues

• Clarify wiimote organization (imu_drivers vs. joystick_drivers). Rather than listing Wiimote under "supported hardware", how about a section such as "Other Devices confirming to the IMU API". This would make it more clear that the wii-mote simply conforms to the API but is otherwise unrelated to this particular stack.

• Should go into a little more detail on the generic imu API. For instance, the fact that it is applicable to the class of IMUs producing orientation, angular velocity, and linear acceleration. Also, a little detail on the imu_data message type could be useful. The relationship between frame_id and the interpretation of the assorted measurements, for instance.

Conclusion