[cmake-developers] Adding some generic section to the docs ?

[Eric Noulard]

2013/1/27 Alexander Neundorf <neundorf at kde.org>:
> Hi,
>
> I'm about to start adding "Generic" sections to the generated documentation.
> This could contain
> * a section about the regeexps supported by cmake, so it doesn't have to be
> documented in the string() and/or if() command
>
> * a section about generator expressions, this appars currently multiple times
> in the docs
>
> * a section about the search order of find_xxx(), which appears currently
> under find_library(), _file(), _path(), _program() and _package()
>
> Comments, objections ?

I find it a very good idea.

I would suggest to use (and may be update) the structured doc parser
I put in place for CPack builtin doc.

see
cmDocumentation.cxx:int cmDocumentation::GetStructuredDocFromFile(...)

Using this we can:
   - put whatever documentation into a text file (which has to be installed
     along with CMake because cmake should be able to parse it when asked for)

   - have easy contribution to CMake documentation.

Currently this is "only" used for CPack*.cmake files.
Have a look at CPack.cmake, CPackComponents.cmaje, etc...

This was designed to document variable and macro/function,
using ##variable and ##macro.
However it also automatically creates new doc sections using
##section
and I did add
##module
in order to put "module-wide" documentation.

Currently the ##section is only parsed for creating the doc section
(and the following content is ignored)
and ##module is parsed but it is not used and its content is not
used either.
(see case SDOC_MODULE: and case SDOC_SECTION: in
 cmDocumentation::GetStructuredDocFromFile)

Adding appropriate support for ##section and/or ##module
would make it possible to write documentation more easily
in a wider set of domain including the one you are targeting.

Off course this may be more work than simply adding documentation
in a bunch of .cxx/.h files so since you'll be doing the work take
that advice "as-is" i.e. a bare wish :-]

That said if you try this road I'll be willing to answer any of your questions
about "cmDocumentation::GetStructuredDocFromFile".


-- 
Erk
Le gouvernement représentatif n'est pas la démocratie --
http://www.le-message.org