2011/10/29 Robert Dailey <rcdai...@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
# - This is the Blah module # This module is documented using reStructuredText syntax. # # With reST, I can use **bold** typeface and *italic* too. # and as you can see http://docutils.sourceforge.net/rst.html, hyperlink # are handled as well. # One can use this small sample module in order to evaluate the possibilities # of using reStructuredText from within CMake comments. # # ``cmake -DCMAKE_MODULE_PATH=. --help-module Blah | rst2html > Blah.html`` [#]_ # # Currently there are several drawbacks to CMake *--help-module* formatting: # * CMake is eating new lines # * CMake does something odd with '-,=,*' characters in column 3 # so that you can't use reST `sectioning format # <http://docutils.sourceforge.net/docs/user/rst/quickref.html#section-structure>`_. # * CMake is putting extra indentation at the beginning and an extra line # at the end. On Linux you can strip them out using extra piped commande like this one: # # ``cmake -DCMAKE_MODULE_PATH=. --help-module Blah | tail -n +2 | head -n -1 | rst2html > Blah.html`` # * CMake may be breaking lines at inappropriate places. # # However this is already usable: # #. because it provides already rich markup # #. because the pure text version is readable too # #. because you may transform the reST into various nicer output # # .. [#] or you can use alternate output format from docutils. # Suppress this line and the previous blank one # # .. role:: param(emphasis) # # .. role:: macro(strong) # # :macro:`mblah` # * :param:`arg1` : should be the first argument # * :param:`arg2` : should be the second argument # # Unfortunately this is not parsed by --help⁻module macro(mblah arg1 arg2) message("mblah called with: ${arg1} ${arg2}" endmacro(mblah)
-- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
