Changes between Version 1 and Version 2 of pm-doxygen


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

Intermediate save.

Legend:

Unmodified
Added
Removed
Modified
  • pm-doxygen

    v1 v2  
    1 = Doxygen in Coin =
     1= Doxygen =
    22
    3 COIN has chosen to use the [http://www.stack.nl/~dimitri/doxygen/ doxygen] program for in-code documentation. Complete [http://www.stack.nl/~dimitri/doxygen/manual.html on-line doxygen documentation] is available there.
     3COIN 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
     5'''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.
     6
     7== Doxygen in COIN ==
     8
     9To 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].
     10
     11For 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.
     12
     13The 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}}}.
     14
     15Why 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.
     16
     17Where can you get the package and project {{{doxygen.conf.in}}} files? Again, 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 project and package configuration files are attached to this page. There are only two differences:
     18 * 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.''
     19 * 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.)