[CMake] Suggestions on documenting my CMake modules

Eric Noulard eric.noulard at gmail.com
Sat Oct 29 17:41:22 EDT 2011


2011/10/29 Robert Dailey <rcdailey at gmail.com>:
> I have several complex functions which require a ton of documentation. I
> wanted to type this documentation directly in the cmake file right above the
> function() itself, but it is turning out to be a formatting nightmare.

What kind of formatting do you need?

> What would you guys recommend as far as this kind of documentation goes?

My opinion is that the documentation of a CMake macro/function should stay
in the same file as macros/function and find a way to extract doc.

CMake can already extract the documentation header from a module using:

cmake --help-module

try for example
cmake --help-module CPack

But you do not get much of formatting, now try the following:

cmake -DCMAKE_MODULE_PATH=. --help-module Blah | tail -n +2 | head -n
-1 | rst2html > Blah.html

with the attached potential "Blah.cmake" script and open the html file.

> It would be great if doxygen could scan CMake scripts and generate HTML
> documentation out of them, but I don't know if this is possible.

The previous idea was for module and not for "function/macro" header
like Doxygen does.
But may be by defining some reST role
(http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles)
we could define relatively good formatting.

Currently CMake --help-module does not seek documentation inside the
cmake script file
after the initial comment blocks stops.
But may be we could change that.

-- 
Erk
Membre de l'April - « promouvoir et défendre le logiciel libre » -
http://www.april.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Blah.cmake
Type: text/x-cmake
Size: 1766 bytes
Desc: not available
URL: <http://www.cmake.org/pipermail/cmake/attachments/20111029/87580e09/attachment.bin>


More information about the CMake mailing list