- Adding documentation to your code
See also: rosdoc_lite, Epydoc, Sphinx
Doxygen documentation: Getting started with doxygen. This section provides an overview of what doxygen is, and why a developer might want to use it. Doxygen is a JavaDoc like documentation system for C, C, Java and IDL.
Doxygen is a tool for auto-generating API documentation, though you can also use it to generate documentation separate from an API. The main advantage of Doxygen is that you can write documentation directly within the comments of your source code. Doxygen searches for source code in your tree and generates API documentation for it.
- Doxygen (/ ˈdɒksidʒən / DOK-see-jən) is a documentation generator and static analysis tool for software source trees. When used as a documentation generator, Doxygen extracts information from specially-formatted comments within the code.
- When the doxygen tool processes one or more input source code files, it produces, by default, in the current working directory, a subdirectory named html, which contains all the HTML files that document that source code, according to the doxygen comments contained in the source code.
You don't need to configure and run Doxygen manually in order to generate documentation for your ROS package. Instead, we recommend that you use the rosdoc_lite tool, which provides common templating and other features.
With ROS packages, we generally use Doxygen to document C++-based code. For Python we generally use Epydoc or Sphinx.
NOTE: this page is not a comprehensive guide to Doxygen. For actual documentation on how to use the Doxygen documentation tool, please see the official Doxygen site.
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. There should only be one mainpage tag in your package, so we usually recommend creating a top-level file, e.g. mainpage.dox, with a mainpage tag. To make things easier, we have created a default template in the rosdoc package, which you can find at rosdoc/templates/mainpage.dox.template. Also, if you use the roscreate-pkg tool to create your package, a mainpage.dox will be generated for you.
NOTE: you have to use C++ comment syntax in this file, e.g., : Miele-lxiv.
The htmlinclude line inputs a nicely formatted version of the package's manifest.xml file.
Doxygen's main strength is that you can include documentation inline with your code. Here is an example geared toward a class that is likely compiled into a library:
The todo tag
Doxygen provides a todo tag, that can be used in any Doxygen-style comment block, e.g.:
Doxygen collects these tags into a 'related page,' providing a nice reference for remaining work. 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.
rosdoc: Default Doxygen Settings
rosdoc comes with default settings that generally work well with packages in ROS. The most important is FILE_PATTERNS: these are the files that Doxygen will look inside of for documentation. By default, this is:
FILE_PATTERNS: *.c *.cpp *.h *.cc *.hh *.py *.dox
You can 'roscd rosdoc' and look at the templates/doxy.template to see the many of the default settings used with Doxygen. For example, IMAGE_PATH is set to the root of the project.
For more information on customizing these settings, please see rosdoc_lite.
Embedding Markdown Pages
If you use markdown a lot, it can be more convenient to create non-api pages of documentation for your package using markdown syntax instead of the regular doxygen syntax.
Doxygen Markdown Support - official documentation
rosdoc_markdown_foo - example package.
- Switch to the root directory of an existing, or new catkin package
Create rosdoc.yaml if not already created
Add the *.md pattern to the build rules
Create a doc folder
Create and fill in doc/mainpage.md, this will form the front page of your doxygen documentation
Create another markdown file, e.g. doc/other.md, this page will automatically be listed under doxygen's *Related Pages* tab.
- From the root of your catkin package, run
Point your browser at /path/to/my_catkin_package/doc/html/index.html to see the results.
If you use git, mark generated files and folders so they don't get pushed to your repository, e.g. in .gitignore in the root of your package.
There are a few doxygen extensions that go beyond regular markdown support, see the official document in the Markdown Extensions section. Notably:
- Table of Contents
- Different format for fenced code blocks
- Simpler tables
- Page and section labels for creating doxygen style references
With this, you can link to other markdown pages by referencing the labels for their pages/sections. e.g. other.md
You should link to this by using the doxygen style reference: