# CMake modules Documentation and Doxygen/breathe tutorial/docs

**URL:** <https://discourse.cmake.org/t/cmake-modules-documentation-and-doxygen-breathe-tutorial-docs/6471>\
**Category:** Code\
**Created:** [September 13, 2022, 3:07pm UTC](https://discourse.cmake.org/t/cmake-modules-documentation-and-doxygen-breathe-tutorial-docs/6471 "2022-09-13T15:07:21Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![leha-bot](https://discourse.cmake.org/user_avatar/discourse.cmake.org/leha-bot/32/921_2.png) [@leha-bot](https://discourse.cmake.org/u/leha-bot)\
**Post date:** [September 13, 2022, 3:07pm UTC](https://discourse.cmake.org/t/cmake-modules-documentation-and-doxygen-breathe-tutorial-docs/6471/1 "2022-09-13T15:07:21Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![ben.boeckel](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/b/ea5d25/32.png) [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)\
**Post date:** [September 14, 2022, 8:55pm UTC](https://discourse.cmake.org/t/cmake-modules-documentation-and-doxygen-breathe-tutorial-docs/6471/2 "2022-09-14T20:55:37Z")

</div>

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](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Utilities/Doxygen/filters/cmake2c.pl)

---

<div class="post-metadata">

**Author:** ![Lecris](https://discourse.cmake.org/user_avatar/discourse.cmake.org/lecris/32/3193_2.png) [@Lecris](https://discourse.cmake.org/u/Lecris)\
**Post date:** [March 16, 2023, 9:51am UTC](https://discourse.cmake.org/t/cmake-modules-documentation-and-doxygen-breathe-tutorial-docs/6471/3 "2023-03-16T09:51:40Z")

</div>

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](https://github.com/doxygen/doxygen/issues/9906)