This section contains instructions on how to use Doxygen with Drake.
Coming soon. See issue #2051 and PR #2359.
Classes that implement the drake::systems::System interface should add a simple diagram documenting their input and output ports using the macro:
@system{ system name/label,
@input_port{input port 1 name} @input_port{input port 2 name},
@output_port{output port 1 name} @output_port{output port 2 name}}
The first argument is the contents of the html table cell inside the box. The recommendation is to use (at least) the system name, but you may also get creative and have images, etc, too. Note that the comma delimiter separates the input and output port listings (there is no comma between ports). Where possible, the names here should match the names given to the ports in the code, so that error messages, debugging, and automatically-generated System diagrams match the documentation.
Some systems have variable numbers of ports, or ports that are created
conditionally. Prefer to add all possible ports to the diagram; see the Adder system
for an example of a system with a variable number of ports. The @system
doxygen tag can be used multiple times to add multiple renders of the system to
the documentation, if the system is most clearly described by a few examples.
We encourage the use of unicode in documentation.
For documenting block diagrams, consider using ascii art. See, for instance,
The Emacs ascii-art-to-unicode package can make
ascii-art block diagrams even prettier by replacing -, |, etc. with unicode
box-drawing characters.
To generate and view Drake's Doxygen website, see: :ref:`Documentation Instructions<documentation-generation-instructions>`.