как получить doxygen, чтобы увидеть документацию макроса препроцессора в файле .F90? - PullRequest
Новая
       24

как получить doxygen, чтобы увидеть документацию макроса препроцессора в файле .F90?

1 голос
/ 20 мая 2019

Я работаю с библиотекой ParallelIO, бесплатной библиотекой программного обеспечения для высокопроизводительных вычислений (HPC) ввода-вывода с NetCDF-подобным API.

В некотором коде фортрана у меня есть файл с именем piolib_mod.F90, который запускается: 

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

Это выдает предупреждение о кислороде: 

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

Но что бы я ни делал, я не могу заставить себя принять определение документации для этого макроса. Я пробовал: 

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

также: 

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

Я пытался исключить эту строку из обработки кислородом: 

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

Но это тоже не работает.

Doxygen может быть сбит с толку концепцией макропроцессора в файле Fortran, но это только 21-й век для вас, дорогие суперкомпьютеры и языки программирования 1960-х годов.

Как мне документировать определение препроцессора с помощью doxygen?

1 Ответ

1 голос
/ 26 мая 2019

То, как я это сделал, состояло в том, чтобы предварительно обработать файлы * .F90 в файлы * .f90, а затем использовать файлы * .f90 для Doxygen.

Вот что сделал трюк в 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 $< > $@

В моем файле configure.ac я настроил Doxygen для чтения нужных мне файлов на Фортране: 

# 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

Это все работает, и теперь у меня есть чистая сборка кислорода без предупреждений. ; -)

...