API review

Proposer: Brian Gerkey

Present at review:

  • Ken, James, Wim, Melonee

Question / concerns / comments

  • Where does each kind of documentation go?
  • How do we handle API vs. usage documentation?
  • What tool should be used for auto-generated Python documentation?

Meeting notes

We have several types of documentation, and two places to put them. We've arrived at the following arrangement:

SVN

Wiki

Library API

X

ROS API

X

Usage

?

?

Tutorial

X

Conceptual

X

Of the X marks above, the one that implies a change is the ROS API: it's currently in the Wiki. The plan is to write a script that converts, en masse, the ROS API documentation that is formatted using ClearSilver templates in the Wiki into some formal spec, to live in the package. The format of this spec is to be defined.

Several other issues were brought up, listed as tasks below.

Two open questions remain:

  • Where do we put usage documentation? Should it be merged with API documentation, or separate? If it's separate, where should it live?
  • What is the recommended authoring system for autogenerated Python documentation? We use a mix of epydoc and sphinx. We can continue this mix, or pick one.

These questions will be resolved in a future meeting.

Conclusion


Wiki: DocumentationPolicy/Reviews/2009-10-30_API_Review (last edited 2009-10-30 19:18:17 by BrianGerkey)