Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is an old version of boost. Click here for the latest version's documentation home page.
PrevUpHomeNext

Configuring Doxygen for Documentation Extraction

This section details the steps necessary to use Doxygen to extract documentation and comments from source code to build a BoostBook document (and transform it into end-user documentation). You will need a somewhat recent version of Doxygen; 1.2.18 or newer should suffice.

Boost.Build can be configured for Doxygen support by editing user-config.jam or site-config.jam to add:

using doxygen : DOXYGEN ;

DOXYGEN should be replaced with the name of the doxygen executable (with full path name). If the right doxygen executable can be found via the path, this parameter can be omitted.

Important

The relative order of declarations in user-config.jam / site-config.jam files is significant. In particular, using doxygen line should come after the using boostbook declaration.

Generating of documentation from source files using Doxygen requires two steps. The first step involves identifying the source files so that Doxygen can process them. The second step is to specify that the output of this process, a file in the Doxygen XML format, is input for a BoostBook document. The following Jamfile.v2 illustrates a simple case of generating reference documentation for the Any library:

project boost/any/doc ;
import boostbook : boostbook ; 
import doxygen : doxygen ;

doxygen any.doxygen : ../../../boost/any.hpp ;
boostbook any : any.doxygen ;

In this example, we generate the Doxygen XML representation in the file any.doxygen from the source file ../../../boost/any.hpp by invocing Doxygen. We then use any.doxygen as a source for the BoostBook target any, which will generate documentation in any format the user requests. The actual sequence of events in this transformation is:

  1. Doxygen parses the header file ../../../boost/any.hpp and outputs a single XML file any.doxygen.
  2. The XSLT processor applies the stylesheet doxygen2boostbook.xsl to transform any.doxygen into the BoostBook file any.xml.
  3. The XSLT processor applies the stylesheet docbook.xsl to transform any.xml into the DocBook XML document any.docbook.
  4. Further transformations may generate HTML, FO, PDF, etc. from any.docbook.
Copyright 2003 Douglas Gregor

PrevUpHomeNext