[CMake] Syntax to document cmake files, functions and macros

[Olivier Croquette]

Hello,

I have quite a few .cmake files that I want to document. They define 
functions, macros, and variables, and I was wondering if there is any 
standard or tooling to help.

Is there a complete specification of the syntax used in the CMake 
distribution itself?

E.g.:

add_executable(<name> [WIN32] [MACOSX_BUNDLE]
                [EXCLUDE_FROM_ALL]
                [source1] [source2 ...])

add_definitions(-DFOO -DBAR ...)

add_custom_target(Name [ALL] [command1 [args1...]]
                   [COMMAND command2 [args2...] ...]
                   [DEPENDS depend depend depend ... ]
                   [BYPRODUCTS [files...]]
                   [WORKING_DIRECTORY dir]
                   [COMMENT comment]
                   [VERBATIM] [USES_TERMINAL]
                   [COMMAND_EXPAND_LISTS]
                   [SOURCES src1 [src2...]])

It looks like the documentation is not completely consistent by the way, 
for instance, the first argument of add_executable is <name>, and of 
add_custom_target is Name, although is same situation, isn't it?


For functions and macros, I can reuse this syntax, is there anything 
similar for documenting a file, or variables?

More generally, is there anything like Doxygen, Javadoc, both in terms 
of syntax and tooling to generate documents from source code?

Olivier