Changes between Version 2 and Version 3 of pm-doxygen


Ignore:
Timestamp:
Sep 27, 2010 8:33:08 PM (9 years ago)
Author:
lou
Comment:

Commit Step 2.

Legend:

Unmodified
Added
Removed
Modified
  • pm-doxygen

    v2 v3  
    22
    33COIN has chosen to use the [http://www.stack.nl/~dimitri/doxygen/ 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 [http://www.coin-or.org/Doxygen/Osi/index.html doxygen documentation generated for Osi]. Complete [http://www.stack.nl/~dimitri/doxygen/manual.html on-line doxygen documentation] is available there.
     4
     5Doxygen 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.
    46
    57'''NOTE''': This page describes the new architecture for generating doxygen documentation. If your project is already set up under the old architecture, note that you will be replacing existing doxygen configuration files. If you've customised an existing doxygen.conf file, save it off to the side so you can restore the customisations after conversion.
     
    1113For the remainder of this page, [https://projects.coin-or.org/Osi Osi] will be the running example. Consult the various files referenced below for examples.
    1214
     15=== Step 1: Install {{{doxygen.conf.in}}} ===
    1316The 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}}}.
    1417
     
    1821 * 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.''
    1922 * 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 project's base source code will be processed at both the project and package levels.)
     23Be careful to put the package and project files in the correct places!
     24
     25'''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.
     26
     27Once 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.
     28
     29=== Step 2: Adjust {{{configure.ac}}} ===
     30
     31The {{{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
     32{{{
     33AC_COIN_DOXYGEN(CoinUtils)
     34}}}
     35The 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:
     36{{{
     37AC_COIN_DOXYGEN(CoinUtils Cgl Clp DyLP Vol SYMPHONY)
     38}}}
     39Doxygen is quite forgiving when it comes to linking with other doxygen documentation; if it can't find the tag file that it uses 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. The net effect is that it may take a few iterations of building and installing the doxygen documentation before all links are in place.
     40
     41In 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}}}
     42{{{
     43AC_CONFIG_FILES([doxydoc/doxygen.conf])
     44}}}
     45This will be the same in the package- and project-level {{{configure.ac}}} files.
     46
     47Configuration sets the 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.
     48There'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 [http://www.graphviz.org graphviz] package) and will disable use of dot if it's not found.
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72