The first step of an API review is for the Author to put together a proposed API for the package. Write this on the main wiki page (created during the package proposal). This should include all externally visible interfaces into the package, including:

• functions, classes, and variables exported by the library
• all topics, services, and parameters exported via ROS
• description of functionality and interactions of specific calls where not clear

For packages with existing code, you are encourage to embed the API documentation in the code, and link to the autogenerated documentation, instead of rewriting it on the wiki.

Also create an API review page, using the button at the bottom of the package page. This will have space for other developers to comment on the API and ask questions.

Create a calendar event on Google Calendar, add guests

willowgarage.com_aqp3iopeia3oahnc9phu2d22b0@group.calendar.google.com,
ros-users@lists.ros.org,
individuals whom you think should attend (not everybody is on ros-review)

Include a link to the API proposal page with the date of the scheduled API review. Give at least 48 hours between sending out the review and the review meeting.

Before the meeting, read through all questions / concerns and prioritize to make sure all critical concerns are covered during the meeting.

At the API review, you (the author / proposer) will run a discussion of the API by covering the issues raised by attendees. The assumption is that attendees will have all read through the API and added their concerns to the page, so covering the list of concerns should be the agenda for the meeting.

At the end of the meeting, Brian or Eric will make the final determination of whether the proposed API is accepted, conditionally accepted, or needs significant re-work.

The next step is implementing, testing, and getting ready for a code review

Questions to ask during an API review

Here are some sample questions to think about when reviewing an API

Code API

1. Is the usage of the API clear?
2. Is the terminology used in the API what you would expect?
3. Is the API/API documentation organized as you would expect?
4. What functions/methods/data types are unnecessary?
5. What functions/methods/data types are missing? (NOTE: a Package should only implement as much API as is going to be used and no more)

msgs and srvs

1. Do the msgs and srvs in the Package belong here or in a higher/lower level Package?

2. Are all msgs appropriate semantic, e.g. (FourFloat64 vs. Quaternion)

3. Are all srvs have method-like rather than data-type names, e.g. (SetMap vs. Map)

launches

1. Do the launches belong with this Package, or in a separate Package? (i.e. are the launch files pulling in additional, unnecessary dependencies)
2. Is it easy to understand what the launch files do by their naming?

Completing a Review

If you have completed API Review, please mark the relevant manifest.xml or stack.xml with API cleared (or API conditionally cleared if changes are required) in the <review> status. Also note the date of the review in the notes attribute. <-- (2/03/2013 This is obsolete after REP127).