DoxyRestruct - coin-or-foundation/tlc GitHub Wiki

The proposal is to bring doxygen documentation into the autotools build structure, as follows:

• Doxygen documentation is built in the build directory rather than the source directory.
• Rather than processing all source (project and externals) every time the documentation is rebuilt, doxygen .tag files are used to stitch the documentation together.
• Introduce a doxydoc directory at the project level (i.e., the same level as the src directory for a project). This directory would hold configuration files to generate doxygen documentation for just the source of the project. The notion is that this documentation would be appropriate for when the project's code is used as an external.
• Reorient the doxydoc directory at the package root (i.e., the existing doxydoc directory) to build documentation for the package. This could include extra source (examples, for instance) that aren't really relevant when the project's code is used as an external.
• Introduce a new autotools macro, AC_COIN_DOXYGEN, that would generate doxygen .conf files from .conf.in files at configure time. Use of dot to get the fancy dependency graphs is optional and off by default. If you include the configure option --with-dot, dot will be used if present. The macro goes in coin.m4.
• Alter the package Makefile.am to include doxydoc and doxydocs targets, analogous to the test and tests targets. Alter project Makefile.am's to include a doxydoc target.

The primary advantage is that when rebuilding the doxygen documentation for, e.g., Cbc, there's no need to reprocess the source for CoinUtils, Clp, Osi, etc. Also, the source for each external is processed separately, which goes a bit faster. PMs should be able to modify the project- and package-level doxygen configuration files to define the appropriate compile-time symbols for their project's source code (and will not need to try and figure out what's right for other projects' source code). Another nice side-effect is that references to external classes are marked as such.

There's one annoying drawback, caused by the circular relationships that exist between many Coin projects. The first time that documentation is built from scratch, all of it must be built twice. The first round generates all the .tag files so that the second round can get all the external links correct.

I have this up and working; here's an outline of the file structure (using Cbc as the example)

Cbc-Package/

• doxydoc/
  • cbc_doxy_pkg.conf.in specifies tag file generation, and external tag files to be used when generating documentation.
• configure.ac includes AC_COIN_DOXYGEN([CoinUtils Clp DyLP Vol Osi Cgl]) and generates doxydoc/cbc_doxy_pkg.conf
• Makefile.am includes doxydocs and doxydoc targets.
• by default, package documentation is the same as project documentation, but can be expanded to include examples, etc., by editing cbc_doxy_pkg.conf.in
• Cbc/
  • doxydoc/
    • cbc_doxy_proj.conf.in
  • configure.ac includes AC_COIN_DOXYGEN([CoinUtils Clp DyLP Vol Osi Cgl]) and generates doxydoc/cbc_doxy_proj.conf.
  • Makefile.am includes doxydoc target.
• CoinUtils/
  • doxydoc/
    • coinutils_doxy_proj.conf.in
  • configure.ac includes AC_COIN_DOXYGEN([Clp Osi]) and generates doxydoc/coinutils_doxy_proj.conf
  • Makefile.am includes doxydoc target.
• Cgl/
  • doxydoc/
    • cgl_doxy_proj.conf.in
  • configure.ac includes AC_COIN_DOXYGEN([CoinUtils Clp Osi]) and generates doxydoc/cgl_doxy_proj.conf
  • Makefile.am includes doxydoc target.
• etc.

Unfortunately, this will require changes on the part of all projects. The payoff is that we'll have a structure that is much more amenable to customisation by individual PMs and will dramatically reduce the time required to do incremental modification or update of the doxygen documentation for a project. This structure should also be more amenable to separation as we move forward toward independent RPMs for each project's package. Doxygen complains when a .tag file is missing, but keeps going. You just don't get links to external classes.

While I'm not entirely sure of the implications, there will likely need to be some changes in the way we capture the doxygen documentation currently served to the public from the repository.