[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