[certi-dev] CERTI documentation with Doxygen HOWTO

[Eric Noulard]

Hi All,

Now that you know that I tried to use doxygen
for CERTI documentation here comes the detail of how it works.

Take a big breath and keep reading :=)

First of all if you want to build the documentation you'll have to
set the BUILD_DOC CMake option to ON using either cmake-gui
or the command line
 cmake -DBUILD_DOC:BOOL=ON

There is 3 sets of documentation

 - Install
 - User
 - Developer

the default when BUILD_DOC is ON is to build Install and User doc
but not Developer because it takes some time to build :=)

for each set there is a specific Doxygen configuration file:

certi/doc/
     certi_install.cnf.in
     certi_user.cnf.in
     certi_developer.cnf.in

those files are CONFIGUREd through CMake CONFIGURE_FILE
in order replace some vars (look for @VAR@ in .in files)

For each Documentation set,one should
indicate the list of input files to be included in the set using the INPUT var
of the concerned Doxygen configuration file, for example the
certi_install.cnf.in contains:

INPUT                  = "${CMAKE_SOURCE_DIR}/doc/certi_install_doc.tree" \
                         "${CMAKE_SOURCE_DIR}/doc/certi_introduction.dox" \
                         "${CMAKE_SOURCE_DIR}/doc/certi_install.dox"

whereas for
certi_user.cnf.in we have:
INPUT                  = "${CMAKE_SOURCE_DIR}/doc/certi_user_doc.tree" \
                         "${CMAKE_SOURCE_DIR}/doc/certi_introduction.dox" \
                         "${CMAKE_SOURCE_DIR}/doc/certi_user.dox"


The rule is the following, certi_xxx_doc.tree is a specific Doxygen file
which defines the documentation top-level structure and
the *.dox files are "documentation element" which may be inclued
for different documentation sets.
Here certi_introduction.dox is the same for the User set and the Install set.

The idea is to define the "documentation information" only once
and use it when needed.

You may create or update as many *.dox files as you want and
then refer to those file inside other Doxygen input files.

*.dox are "pure documentation", but you may in fact
add doxygen markup in almost _ANY_ files, and in the first place sources files.

When you are in source files a Doxygen blocs should be written as a C
style comment like this:
/**
 * An abstract Clock class.
 * Clock abstraction which tries to use high-resolution
 * system clock in order to be able to help user to
 * profile it's application using simple clock API.
 * Derived class will use effective clock API like
 * POSIX clock_xxxx functions:
 * http://www.opengroup.org/onlinepubs/000095399/functions/clock_getres.html
 * or other hardware assisted clock like Pentium TSC.
 */
class CERTI_EXPORT Clock {
....
}

One should off course document every classes and every methods
with appropriate markup.

If you the documentation set to include the Doxygen documentation found
in a source file you should add the file to the INPUT list of the
specific Doxygen config file.

That's enough for one mail.
There are many things Doxygen can do, If you don't know how to do something,
just ask and I'll try to answer.

Please give feedback on the produced doc, and the way i works.
-- 
Erk