Contents
Kinds of documentation
We divide documentation into the following categories:
Each category is defined below.
Where to put documentation
We keep documentation in two places:
- in Subversion (or other version control system), with the code; and
- in the wiki.
The following table shows where each kind of documentation should go:
|
Subversion |
Wiki |
Conceptual |
|
X |
API |
X* |
|
Usage |
|
X |
Tutorial |
|
X |
In other words, only API documentation goes into Subversion. As noted below, nearly all API documentation should be autogenerated by a tool.
[*] Most ROS API documentation is currently in the wiki, using the CS/NodeAPI template. The plan is to move this information into Subversion, to live in the package, in a structured fashion. Until this structured format is defined, ROS APIs will continue to be documented in the wiki. All other API documentation goes in Subversion.
Documentation tools
rosdoc supports the use of different tools for auto-generation of API documentation, such as Doxygen, Sphinx, and Epydoc. For each package with API documentation, exactly one tool must be chosen per API (see rosdoc for details on choosing a tool). This choice rests with the author or maintainer, with the following guidance:
- C++ : Doxygen
- Python : Epydoc or Sphinx
While the choice of documentation tool for a package can change, it should not be done lightly, and not without a good reason.
If your package has multiple APIs, e.g. both C++ and Python, the APIs should be documented separately. rosdoc enables you to do this using rosdoc configuration files.
Definitions of documentation categories
Note : You'll surely come across a piece of documentation, or a documentation need, that could reasonably be put into more than one category. In this case, pick a category that makes sense to you, and don't agonize over the decision. It's far more important to write sufficient, correct documentation than to ensure that documentation is correctly categorized.
Conceptual documentation
It is sometimes necessary to document concepts that are not specific to a particular package, language, or library. The best example of this kind of documentation is the discussion of ROS-wide concepts.
Conceptual documentation need not be at the ROS level. E.g., a discussion of the purpose and role of transforms (as opposed to documentation on using tf) would be conceptual.
API documentation
API documentation provides information on how to call into a module. The goal of API documentation is to provide the user with enough detail to use all parts of the public interface provided by a particular module.
This kind of documentation includes:
functions and methods, including call signature (type and order of arguments, return value) and description of behavior
class members, including type and interpretation
command-line usage, including order and type arguments
ROS API, including published and subscribed topics, advertised and called services, and referenced parameters
API documentation often takes the form of an index of interface components, and is usually concise, without much narrative. Whenever possible (which is most of the time), API documentation is autogenerated from structured comments in the code. See tools.
Usage documentation
Usage documentation provides information on how to use important parts of a module, without a focus on any particular task. The goal of usage documentation is provide the user with enough background and examples to effectively use a module.
This kind of documentation includes:
listing of key API components, to separate them out from the full API index
common sequences of variable instantiations, function and method calls
brief examples of common usage
Usage documentation usually comprises a set of short narrative sections, with many sections accompanied by code examples.
Usage documentation does not tell you what arguments a function accepts; that's API documentation. Usage documentation does not step you through achieving a non-trivial task; that's tutorial.
If a particular section is version-specific, that version should be clearly noted. Similarly, if a section relates to a volatile API, that volatility should be clearly conveyed to the reader.
Tutorials
Tutorials provide step-by-step instruction on how to achieve a particular task. The goal of a tutorial is teach the user how to do something. Ideally the task for the tutorial should be aligned with what the user actually will use the code for, e.g. the navigation tutorials teach a user how to port the navigation stack to a robot.
A tutorial usually combines code samples with prose that explains what the code is doing.
Reviews
See /Reviews
