rosdoc

[http://pr.willowgarage.com/pr-docs/ros-packages/rosdoc/html/index.html Auto-generated code documentation]

TableOfContents(3)

rosdoc provides auto-documentation capabilities across ROS packages via doxygen. It is mainly used to automatically generate documentation on the PR web server, but it can also be invoked manually. Nightly updates are made to:

• [http://pr.willowgarage.com/pr-docs/ros-packages]

Building the documentation

To build all the docs:

$ cd $ROS_ROOT/core/rosdoc/
$ make clean
$ make doc

To only build docs for some packages:

$ cd $ROS_ROOT/core/rosdoc/
$ ./rosdoc hokuyourg_player nav_view

In either case, the documentation goes into the subdirectory doc. Open doc/index.html with a web browser.

Adding documentation to your code

You can use any Doxygen markup in your code. The first thing you'll probably want to do is use the @mainpage tag. E.g., in C++:

/**

@mainpage

@htmlinclude manifest.html

@b nav_view is....

**/

The @htmlinclude line inputs a nicely formatted version of the package's [:ROS/Manifest:manifest.xml] file. Other special tweaks may come later. For a ROS node, you should always document the following aspects:

• usage : how to launch the node, including any command-line arguments

• topics : which topics a node subscribes and publishes to. For each topic, give the name, message type, and semantics.

• parameters : names, types, and interpretation of all parameters that can be set via the param server

Continuing the nav_view example:

@section usage Usage
@verbatim
$ nav_view [map res] [standard ROS args]
@endverbatim

@param map An image file to load as an occupancy grid map. The lower-left pixel of the map is assigned the pose (0,0,0).
@param res The resolution of the map, in meters, pixel.

@todo Remove the map and res arguments in favor map retrieval via ROSRPC.

@par Example

@verbatim
$ nav_view mymap.png 0.1 odom:=localizedpose
@endverbatim

@par GUI controls
Mouse bindings:
- drag left button: pan view
- drag right button: zoom view
- click middle button: send goal

<hr>

@section topic ROS topics

Subscribes to (name/type):
- @b "odom"/RobotBase2DOdom : the robot's 2D pose.  Rendered as a circle with a heading line.
- @b "particlecloud"/ParticleCloud2D : a set particles from a probabilistic localization system.  Rendered is a set of small arrows.
- @b "gui_path"/Polyline2D : a path from a planner.  Rendered as a dashed line.
- @b "gui_laser"/Polyline2D : re-projected laser scan from a planner.  Rendered as a set of points.

Publishes to (name / type):
- @b "goal"/Planner2DGoal : goal for planner.  Sent on middle button click.

<hr>

@section parameters ROS parameters

- None

The resulting documentation looks like this:

• [http://pr.willowgarage.com/pr-docs/ros-packages/nav_view/html/index.html]

Another example, more geared toward a class that is likely compiled into a library:

//* A name class
/**
* The basic class description, it does:
* 1. blah
* 2. blah ....
*  
*/
class NameOneTwo
{
  public:
    /*!
    * \brief This description shows up at the top of the doxygen so you don't have to scroll.
    *
    * This description is displayed lower in the doxygen as an extended description along with
    * the above brief description.
    * \param junk       This is a cool junk varible
    */
    int MethodOne( int junk);

    /*!
    * \brief This description shows up at the top of the doxygen so you don't have to scroll.
    *
    * This description is displayed lower in the doxygen as an extended description along with
    * the above brief description.
    */
    int MethodTwo();

  private:
    int var_abc;                /**< A variable (i.e. it does something special). */
    int error_number;     /**< A variable that can be confused with the other variable. */
    string* name;           /**< A variable that is the coolest. */
}

The @todo tag

Doxygen provides a @todo tag, that can be used in any Doxygen-style comment block, e.g.:

/** @todo Make the value externally configurable */
double distance = 1.0;

Doxygen collects these tags into a "related page," providing a nice reference for remaining work, e.g.:

http://pr.willowgarage.com/pr-docs/ros-packages/wavefront_player/html/todo.html

This is better than using //TODO or //FIXME or whatever other comments you might normally use, because it makes the todo-ness externally visible.

Please use the @todo tag wherever applicable.

Auto-doc tweaks via manifest.xml

rosdoc for packages with external documentation

You can force rosdoc to link to a package's external Web documentation by modifying the ["Manifest"] to include the following export tag:

<export>
  ... other export tags
  <doxymaker external="http://external/documentation.html" />
</export>

This also disables the local doxygen build against this package.

Reasons you may wish to do this include:

• External documentation is likely better
• doxygen on a large thirdparty package takes a long time

CategoryPackage