CODEWITHSUNDEEP
fortrandoxygen
Edward Hartnett
Edward Hartnett

Reputation: 961

how to get doxygen to see documentation of preprocessor macro in .F90 file?

I am working with the ParallelIO library, a free software library for high performance computing (HPC) I/O with a netCDF-like API.

In some fortran code I have a file called piolib_mod.F90 that starts:

!>
!! @file
!! @brief Initialization Routines for PIO
#define __PIO_FILE__ "piolib_mod.F90"

This produces a doxygen warning:

/home/ed/tmp/ParallelIO/src/flib/piolib_mod.F90:4: warning: Member __PIO_FILE__ (macro definition) of file piolib_mod.F90 is not documented.

But no matter what I do, I can't doxygen to accept my definition of the documentation for this macro. I have tried:

!> for debugging
#define __PIO_FILE__ "piolib_mod.f90"

also:

!> @def __PIO_FILE__ for debugging
#define __PIO_FILE__ "piolib_mod.f90"

I have tried to exclude this line from doxygen processing:

!> @cond exclude
#define __PIO_FILE__ 'piodarray'
!> @endcond

But that does not work either.

Doxygen may be confused by the concept of a pre-processor macro in a Fortran file, but that's just the 21st Century for you, expensive supercomputers and programming languages from the 1960s.

How do I document this pre-processor define with doxygen?

Upvotes: 1

Views: 172

Answers (1)

Edward Hartnett
Edward Hartnett

Reputation: 961

The way I accomplished this was to pre-process the *.F90 files into *.f90 files, and then use the *.f90 files for Doxygen.

Here's what did the trick in Makefile.am:

# Doxygen does not cope well with pre-processor use in Fortran. So
# create .f90 files from .F90 files by running the C
# pre-processor. These will only be used by doxygen when --enable-docs
# is used at configure.
if BUILD_DOCS
BUILT_SOURCES += piodarray.f90 piolib_mod.f90 pionfatt_mod.f90 pionfget_mod.f90 pionfput_mod.f90 pionfatt_mod_2.f90 pionfget_mod_2.f90
piodarray.f90: piodarray.F90
    $(CC) -E $< > $@
piolib_mod.f90: piolib_mod.F90
    $(CC) -E $< > $@
pionfatt_mod.f90: pionfatt_mod.F90
    $(CC) -E $< > $@
pionfget_mod.f90: pionfget_mod.F90
    $(CC) -E $< > $@
pionfput_mod.f90: pionfput_mod.F90
    $(CC) -E $< > $@

In my configure.ac I set up Doxygen to read the Fortran files I need:

# If building docs, process Doxyfile.in into Doxyfile.
if test "x$enable_docs" = xyes; then
   AC_SUBST([CMAKE_CURRENT_SOURCE_DIR], ["."])
   AC_SUBST([CMAKE_BINARY_DIR], [".."])
   if test "x$enable_fortran" = xno; then
      AC_MSG_ERROR([--enable-fortran is required for documentation builds.])
   fi
   AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib/piodarray.f90  ../src/flib/pio.F90  ../src/flib/pio_kinds.F90  ../src/flib/piolib_mod.f90  ../src/flib/pionfatt_mod_2.f90  ../src/flib/pio_nf.F90  ../src/flib/pionfget_mod_2.f90  ../src/flib/pionfput_mod.f90  ../src/flib/pio_support.F90  ../src/flib/pio_types.F90"])
   if test "x$enable_developer_docs" = xyes; then
      AC_SUBST([C_SRC_FILES], ["../src/clib"])
   else
      AC_SUBST([C_SRC_FILES], ["../src/clib/pio_nc.c ../src/clib/pio_nc4.c ../src/clib/pio_darray.c ../src/clib/pio_get_nc.c ../src/clib/pio_put_nc.c ../src/clib/pioc_support.c ../src/clib/pioc.c ../src/clib/pio_file.c ../src/clib/pio.h"])
   fi
   AC_CONFIG_FILES([doc/Doxyfile])
fi

This all works and now I have a clean doxygen build with no warnings. ;-)

Upvotes: 1

Related Questions