CMake modules Documentation and Doxygen/breathe tutorial/docs

Code
1

Hello, it would be great if there will be any docs about proper CMake modules docs (pun not intended).
E.g., how is better to document the Doxygen-like thinks like @brief, @param, @returns, @example, etc
and how it integrate with Doxygen/Breathe docs.

Thanks in advance for your attention.

1 Like
2

VTK does this by using a Perl script that keeps comments and top-level names, but strips out everything else. This way it looks like a C declaration and Doxygen can do its normal thing. Here’s the script: https://gitlab.kitware.com/vtk/vtk/-/blob/master/Utilities/Doxygen/filters/cmake2c.pl

1 Like
3

It would be nice to have a cmake/doxygen standardized syntax for this, e.g. how to format the comment blocks, a bundled translator, etc.

I have considered that approach, but I believe it is insufficient for what people would want to document:

  • macro, function: More or less translatable, but it is hard to deal with cmake_parse_arguments, specify set(PARENT_SCOPE), return(PROPAGATE), etc.
  • option, set(CACHE): No C alternatives to map these
  • target, export(TARGET), find_package(COMPONENT): No C alternatives
  • add_custom_command, add_custom_target: No C alternatives

On the Doxygen side, it should be possible by defining new language for cmake for xml export specifically. Then we can have some control on what metadata to export for each of these.

Relevant doxygen issue