Documenting C++ Pinocchio

[nmansard]

We need to start to a general framework to produce the documentation of Pinocchio. Two documentations would be useful: one for the C++ API; a second one for the Python interface.

I open the discussion here about the C++ documentation. The best candidate for documentation is Doxygen. Then main issue is to hide the CRTP complexity in the documentation. Right now, I consider that the Doxygen HTML is not usable by novice.

I take a look at Eigen documentation.
http://eigen.tuxfamily.org/dox/index.html
The documentation is organized by "modules". See for example the modules "QR", "LLT", etc for the dense solvers of Eigen:
http://eigen.tuxfamily.org/dox/group__DenseLinearSolvers__Reference.html

In addition, the modules are wrapped in a tutorial-style chapter organization. Finally, the class are listed (while hiding internal classes).

I like the organization by modules. We could have the following modules:

• spatial
• multibody model
• joints
• algorithms
• python interface ===> maybe not to document

I think that it would also be important to accurately select which C++ objects, types, classes and namespaces we want to expose to the documentation. If we reason module by module, it should be pretty evident to chose which to hide.

The bad point is that I do not understand (yet) how the documentation of Eigen is generated. They used advance doxygen features that I do not fully catch.

From the exposition in the doc of the main classes organized by modules, we can complete the doc with presentation pages, tutorials, etc.

[olivier-stasse]

Stating the obvious, I do not think the documentation is inside the header files.

[jmirabel]

👍 for a documentation by modules.

Is this an ongoing process ?

[nmansard]

Yes somehow. A template of the new doxygen is in, which wait for completion. We did not share the documentation work yet.

[jmirabel]

Doxygen uses the C-preprocessor of CPP files, so the section with:

#ifdef WITH_HPP_FCL
...
#endif

are hidden in the doc.

To enable them, either deactivate the preprocessing via ENABLE_PREPROCESSING = NO or use PREDEFINED = WITH_HPP_FCL to define the right preprocessor variable.

For further reading, see https://www.stack.nl/~dimitri/doxygen/manual/preprocessing.html