wiki:pm-doxygen

Version 6 (modified by lou, 9 years ago) (diff)

Formatting typo

Doxygen

COIN has chosen to use the doxygen program for in-code documentation. Briefly, documentation is generated by scanning source files (by default, only .h and .hpp files) which have been annotated with comments and doxygen markup. As an example, here's the doxygen documentation generated for Osi. Complete on-line doxygen documentation is available there.

Doxygen documentation can be built and installed just as the code is built and installed. Doxygen documentation for a given project or package can be linked with doxygen documentation for other projects or packages, within the limits of doxygen's ability.

Doxygen in COIN

NOTE: This page describes the new architecture for generating doxygen documentation. At present (100927) it is only available when you use the BuildTools trunk. If your project is already set up under the old architecture, you will be replacing the existing doxygen.conf configuration file. If you've customised it, save it off to the side so you can restore the customisations after conversion.

To use doxygen within the COIN build system, you should first document your code using doxygen markup. Doxygen markup is designed to be minimally intrusive and works well with common styles of in-code documentation. Even with zero markup, doxygen will still generate minimal documentation showing classes and structures, their members, and their interrelationships (e.g., DyLP). Consult the source code for any of the COIN projects that have documentation here.

For the remainder of this page, Osi will be the running example. Replace 'Osi' with the name of your project. Consult the various files referenced below for examples.

Step 1: Install doxygen.conf.in

The next step is to add doxygen configuration files (by default, doxygen.conf) to control the documentation that doxygen produces. As with many other files, these are customised by the configure script, so you're really adding doxygen.conf.in. You'll have two of these, one at the top level of the project's package, Osi/doxydoc/doxygen.conf.in, and one in the project's main directory, Osi/Osi/doxydoc/doxygen.conf.in.

Why two? The short answer is flexibility. Traditionally, the COIN package for a project has been assembled by specifying dependencies as externals. Osi/doxydoc/doxygen.conf.in will be used only with the Osi package. Osi/Osi/doxydoc/doxygen.conf.in will be used whenever some other project uses Osi as an external. If you wish, you can exploit this, adjusting the package-level doxygen.conf.in to produce additional documentation appropriate for the package but not necessary when the code is being used as an external.

Where can you get the package and project doxygen.conf.in files? The best approach is to grab them from a project that's already set up, just to ensure that you have the most current version. For convenience, however, vanilla package and project configuration files are attached to this page. There are only two differences:

  • In the package file, INPUT = @abs_top_srcdir@; in the project file, INPUT = @abs_top_srcdir@/src. Thus the project file will include only the project's base source code. The package file will also pick up unit tests, examples, etc.
  • In the package file, EXCLUDE_PATTERNS = */.svn* @coin_doxy_excludes@; in the project file, EXCLUDE_PATTERNS = */.svn*. This allows configuration to exclude the source code of externals, so that it is not processed a second time at the package level. (For technical reasons, the job of ensuring that the project's base source code is not processed twice is handled by Makefile.am. There are some other fine points; consult the macro definition in coin.m4 if you're interested.)

Be careful to put the package and project files in the correct places!

If you're converting your project from the old style of generating doxygen documentation and you've customised Osi/doxydoc/doxygen.conf, transfer any customisations to Osi/doxydoc/doxygen.conf.in or Osi/Osi/doxydoc/doxygen.conf.in, as appropriate.

Once you've installed the doxygen.conf.in files, you may wish to adjust them for your project's code. In particular, look at the section titled `Configuration options related to the preprocessor' and consider whether you want to instruct doxygen to consider compilation-time macro definitions. For example, the entire content of OsiDylpSolverInterface.hpp is wrapped with #ifdef COIN_HAS_DYLP ... #endif. The project-level doxygen.conf.in file includes

PREDEFINED = COIN_HAS_DYLP

Without this, doxygen would simply see an empty file.

Step 2: Adjust configure.ac

The AC_COIN_DOXYGEN macro is provided to configure doxygen processing. The parameter is a space-separated list of other projects whose doxygen documentation should be linked with the documentation of the current project. For example, the Osi library depends on CoinUtils, and the project-level configure.ac specifies this dependency as

AC_COIN_DOXYGEN(CoinUtils)

The Osi package takes a broader view. There are many implementations of the Osi interface, and it's useful, when browsing the Osi documentation, to be aware of them. The package level configure.ac specifies the relevant projects so that doxygen can determine which projects reimplement a particular method:

AC_COIN_DOXYGEN(CoinUtils Cgl Clp DyLP Vol SYMPHONY)

Doxygen is quite forgiving when it comes to linking with other doxygen documentation; if it can't find a tag file that it wants for linking, you'll get a warning in the log file, but that's all. However, doxygen does not do any sort of global linking, nor does it rebuild documentation that is the target of a link. It looks in a specified tag file for a match; if it finds one, it generates a link. The net effect is that it may take a few iterations of building and installing the doxygen documentation before all links are in place.

In addition to a call to AC_COIN_DOXYGEN, you'll need to add a call to AC_CONFIG_FILES so that configure will process doxygen.conf.in into doxygen.conf

AC_CONFIG_FILES([doxydoc/doxygen.conf])

This will be the same in the package- and project-level configure.ac files.

Configuration sets a number of variables in the doxydoc.conf.in files so that doxygen can locate source code and the tag files that allow linking with other projects' documentation. There's one other configuration option, --with-dot, which controls doxygen's generation of inheritance and collaboration graphs. This is on by default but somewhat expensive; to disable it specify --without-dot as a configure option. Configure will check for the dot tool (part of the graphviz package) and will disable use of dot if it's not found.

Step 3: Modify Makefile.am

The last step is to add the necessary lines to the package- and project-level Makefile.am to build and install the doxygen documentation. Again, the best approach is to go and look at a project that's already set up. But for convenience, here are the relevant portions from the Osi Makefile.am files.

In the package-level Makefile.am, add

# Generate doxygen doc'n in subdirectories (except @PACKAGE_NAME@) if a doxydoc
# directory is present, then do the base, if present.

doxydoc:
        for dir in $(subdirs) ; do \
          if test $$dir != @PACKAGE_NAME@ && test -r $$dir/doxydoc ; then \
            (cd $$dir ; $(MAKE) doxydoc) \
          fi ; \
        done ; \
        if test -r doxydoc/doxygen.conf ; then \
          doxygen doxydoc/doxygen.conf ; \
        fi

clean-doxydoc:
        ( cd doxydoc ; rm -rf html *.log *.tag )

# DocInstallDir is defined in Makemain.inc and is specific to the package.
# For the short term, adopt the notion that we install only the package
# doxydoc.

install-doxydoc: doxydoc
        if test -r doxydoc/doxygen.conf ; then \
          $(mkdir_p) $(DocInstallDir) ; \
          cp -R doxydoc $(DocInstallDir) ; \
        fi

uninstall-doxydoc:
        rm -rf $(DocInstallDir)/doxydoc

clean-local: clean-doxydoc
uninstall-local: uninstall-doxydoc

Add doxydoc to the list of .PHONY targets.

For the project-level Makefile.am, add

# Doxygen documentation

doxydoc:
        doxygen doxydoc/doxygen.conf

clean-doxydoc:
        ( cd doxydoc ; rm -rf html *.log *.tag )

Add doxydoc to the list of .PHONY targets, and add clean-doxydoc to the list of clean-local targets.

Attachments (2)

Download all attachments as: .zip