Documenting CMake Scripts and Formatting

Usage
1

Hello everybody,

I’m working on a project to convert an existing Makefile project to CMake. I want to start documenting all of the variables, macros, functions, and files I’ve created but haven’t found a standardized way of doing so. I’m used to documenting C/C++ code using the Doxygen format so I’ve been trying to find something similar to what Doxygen describes, but for CMake code. I’m also curious if there are any standardized ways of formatting CMake code. Any help or examples would be greatly appreciated, thanks!

2

We stuff vtkModule.cmake through Sphinx using block comments. See the modern version or look at a historical version which used Doxygen syntax. I’m not intimately familiar with how it is/was hooked into the documentation process, but Doxygen at least output it like an old K&R C-style function declaration.

3

Doxygen has a notion of “filters”, which is basically a preprocessing script that it runs on files with certain extensions. So the idea is that you can set up a custom filter for .cmake files that would process them to output a C-like syntax that Doxygen understands. Such a script might take the following CMake script:

#[[ Extra verbose documentation ]]
set(MY_VAR 0 CACHE STRING "Some doc string")

#[[ Extra verbose documentation ]] 
function(my_func target number)
endfunction()

and output the following fake C header file for Doxygen to parse:

/** Extra verbose documentation */
const int MY_VAR = 0;

/** Extra verbose documentation */
void my_func(const char* target, int number);

Writing a script like this does require a bit of effort, especially when it comes to handling function parameters, but it is totally doable.

IIRC CMake’s own documentation uses Sphynx rather than Doxygen, which has its own set of workarounds, but it can work using either system.