Changes between Version 4 and Version 5 of pm-doxygen


Ignore:
Timestamp:
Sep 27, 2010 9:23:11 PM (9 years ago)
Author:
lou
Comment:

Final tweaks.

Legend:

Unmodified
Added
Removed
Modified
  • pm-doxygen

    v4 v5  
    55Doxygen 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.
    66
    7 '''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.
    8 
    97== Doxygen in COIN ==
    108
    11 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. Consult the source code for any of the COIN projects that have documentation at [http://www.coin-or.org/Doxygen here].
     9'''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.
    1210
    13 For 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.
     11To 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.'', [http://www.coin-or.org/Doxygen/DyLP DyLP]). Consult the source code for any of the COIN projects that have documentation [http://www.coin-or.org/Doxygen here].
     12
     13For the remainder of this page, [https://projects.coin-or.org/Osi Osi] will be the running example.
     14Replace 'Osi' with the name of your project. Consult the various files referenced below for examples.
    1415
    1516=== Step 1: Install {{{doxygen.conf.in}}} ===
    16 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}}}.
     17The 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}}}.
    1718
    18 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}}} to produce additional documentation appropriate for the package but not necessary when the code is being used as an external.
     19Why 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.
    1920
    20 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 insure that you have the most current version. For convenience, however, vanilla [attachment:doxygen.conf.in.pkg package] and [attachment:doxygen.conf.in.proj project] configuration files are attached to this page. There are only two differences:
     21Where 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 [attachment:doxygen.conf.in.pkg package] and [attachment:doxygen.conf.in.proj project] configuration files are attached to this page. There are only two differences:
    2122 * 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.''
    22  * 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 only at the package level; this is handled by {{{Makefile.am}}}.)
     23 * 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 [source:trunk/coin.m4 coin.m4] if you're interested.)
    2324Be careful to put the package and project files in the correct places!
    2425
     
    2627
    2728Once 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.
     29For example, the entire content of {{{OsiDylpSolverInterface.hpp}}} is wrapped with {{{#ifdef COIN_HAS_DYLP ... #endif}}}. The project-level {{{doxygen.conf.in}}} file includes
     30{{{
     31PREDEFINED = COIN_HAS_DYLP
     32}}}
     33Without this, doxygen would simply see an empty file.
     34
     35
    2836
    2937=== Step 2: Adjust {{{configure.ac}}} ===
     
    3745AC_COIN_DOXYGEN(CoinUtils Cgl Clp DyLP Vol SYMPHONY)
    3846}}}
    39 Doxygen 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.
     47Doxygen 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.
    4048
    4149In 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}}}
     
    4553This will be the same in the package- and project-level {{{configure.ac}}} files.
    4654
    47 Configuration 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.
     55Configuration 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.
    4856There'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.
    4957