How to document ROS2 C++ package source code?

Question

What's the current best practice to document ROS2 (Bouncy, colcon build) C++ package source code? (According to ros2doc templates it seems like the sphinx extension breathe is used to post process doxygen generated docs.)

---

Originally posted by thinwybk on ROS Answers with karma: 468 on 2018-08-19

Post score: 1

---

Original comments

Comment by William on 2018-08-21:
That's still the plan I think. For now, I'd just use doxygen with c++ and if you want create a doxygen file in your project so it can generate documents you can do that, but what's in it may need to change in the future.

Answer 1

There is not yet any defined best practice on documenting ROS2 packages. The ROS2 style guide does give some information on what should be in the documentation, but it does not prescribe a format. Use what you are familiar with, what is easy to maintain, and what produces good, readable documentation.

---

Originally posted by Geoff with karma: 4203 on 2018-08-20

This answer was ACCEPTED on the original site

Post score: 1

---

Original comments

Comment by thinwybk on 2018-08-21:
The main thing I am interested in is integrating nicely with the future ROS2 API build infrastructure which will generate http://docs.ros2.org/api/ (not existing yet).

Comment by Geoff on 2018-08-21:
If you are looking to be compatible with something that does not exist yet, then I don't think there's any answer that will help you. I suggest you use what you've already found, since they are common tools, and update when necessary.

Comment by thinwybk on 2018-08-22:
Usually some people have already something in mind which is not public yet. I just tried to get this Info already. As you said sticking to something common and migrating if necessary is a good idea.