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

Question

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?

Is it because doxygen only runs its preprocessor on fortran files with uppercase extensions (.F90 instead of .f90) ? — L. Scott Johnson, May 20 '19 at 18:43
The file I'm using has an .F90 extension so the pre-processor is being run. — Edward Hartnett, May 20 '19 at 20:53
The preprocessor / preprocessor directives are not part of the Fortran standard (to the best of my knowledge) and I think this is the reason that there is no possibility to document them. — albert, May 21 '19 at 12:17
I saw the edit regarding the '\cond` so I did some tests. It looks like the problem is specific for `.F90` files, when, just for the test(!!), created the same file with `.f90` no warnings are given and the define is not shown (with and without the `\cond`). Looks like a problem with the preprocessing of the Fortran files (there is no option to disable the preprocessing in doxygen other than to rename the file to a lowercase `.f90` file). Please file n issue report in the doxygen issue tracker: https://github.com/doxygen/doxygen/issues/new — albert, May 21 '19 at 16:30

score 1 · Answer 1 · answered May 26 '19 at 13:54

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. ;-)

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

1 Answers1