Re: [certi-dev] New documenation generation system for CERTI

[Eric Noulard]

2008/10/13 Gotthard, Petr <address@hidden>:
> Hi Eric,
> is there a way how to combine install/user documentation from various
> C++ sources?

You should already have part of the answer with my previous mail.
The other part may be the following.

Use \defgroup in your C++ files then use \copydoc in the
specific User or Install documentation.

A working example is the documentation of the RTIA executable
it is located in certi/RTIA/main.cc:

/**
 * @defgroup certi_executable_RTIA RTIA
 *
 * RTIA is the RunTime Infrastructure Ambassador. RTIA is launched
(fork/CreateProcess) by the RTIambassador
 * constructor.
 * \par rtia [-v] [-p \<port\>]
 * \par
 * <ul>
 *   <li> \b -v  (optional) verbose, display more information </li>
 *   <li> \b -p  (optional) tcp port to be used to communicate with
FederateAmbassador</li>
 * </ul>
 *
 * @ingroup certi_executable
 */

Then it is "used" in in certi/doc/certi_user.dox with \copydoc:

 * \subsection certi_user_rtia RTIA CERTI RunTime Infrastructure
Ambassador aka RTIA
 *
 * \copydoc certi_executable_RTIA

If you this to work for other C++ files you need to add
those files in the INPUT list of either
certi/doc/certi_install.cnf.in
certi/doc/certi_user.cnf.in

> When writing the namespace/class (i.e. developer) documentation you
> create "groups" and put documentation from different C++ files to
> different groups. The different groups the appear as different .html
> pages, but each group has a single page.
> http://www.stack.nl/~dimitri/doxygen/grouping.html

If you want to build a group from different C++ source you may
use \addtogroup or \ingroup.

> Yesterday I tried (and failed) to convince doxygen to do the same for
> install/user documentation. For example, environment variables. We can
> write environment variables documentation into respective C++ files, but
> I can only make each variable to have a separate page. It would be nice
> if we could have one .html page listing all variables, but having the
> doxy-source in multiple C++ files. (If you know what I mean.)

Yes I understand normally \copydoc should do something like that (I think)

>  --> If this is not the case and we can have only 1C++ file = 1HTML page
> (of install/user documentation), then we would need some page naming
> conventions and referencing rules.

No you are right User and Install documentation shoud be compact,
Developer doc may be verbose I think it's not a problem.

I tried to make User and Install doc set more compact by
selecting appropriate Doxygen options in their specific conf file.

If it's not "enough" we may try harder.

-- 
Erk