Merge pull request ESMCI#1441 from NCAR/ejh_docs_8

fix last of doxygen warnings, new warnings will cause documentation build to fail
rfiorella · May 22, 2019 · 04234a4 · 04234a4
2 parents 56c19ba + fafbaea
commit 04234a4
Show file tree

Hide file tree

Showing 6 changed files with 72 additions and 11 deletions.
diff --git a/configure.ac b/configure.ac
@@ -136,7 +136,7 @@ if test "x$enable_docs" = xyes; then
       AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib"])
    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"])
-      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.f90  ../src/flib/pio_nf.F90  ../src/flib/pionfget_mod.f90  ../src/flib/pionfput_mod.f90  ../src/flib/pio_support.F90  ../src/flib/pio_types.F90"])
+      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"])
 #      AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib/pio_types.F90 ../src/flib/piodarray.F90 ../src/flib/piolib_mod.F90 ../src/flib/pio_nf.F90"])
    fi
    AC_CONFIG_FILES([doc/Doxyfile])

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
@@ -756,7 +756,7 @@ WARN_FORMAT            = "$file:$line: $text"
 # messages should be written. If left blank the output is written to standard
 # error (stderr).
 
-WARN_LOGFILE           =
+WARN_LOGFILE           = doxywarn.log
 
 #---------------------------------------------------------------------------
 # Configuration options related to the input files

diff --git a/doc/Makefile.am b/doc/Makefile.am
@@ -5,11 +5,10 @@
 EXTRA_DIST = CMakeLists.txt customdoxygen.css Doxyfile.in	\
 DoxygenLayout.xml doxygen.sty
 
-# simple doxygen target
+# Run doxygen, then confirm warning log file is empty.
+check: all
 all:
 	doxygen Doxyfile
+	[ ! -s doxywarn.log ]
 
-# clean up the extras including doxygen
-#clean-local:
-#	cd ${top_srcdir}
-#	rm -rf doxygen
+CLEANFILES = *.log
diff --git a/src/flib/Makefile.am b/src/flib/Makefile.am
@@ -77,7 +77,7 @@ include_HEADERS = $(MODFILES)
 # 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
+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
@@ -88,6 +88,67 @@ pionfget_mod.f90: pionfget_mod.F90
 	$(CC) -E $< > $@
 pionfput_mod.f90: pionfput_mod.F90
 	$(CC) -E $< > $@
+
+# Unfortunately the genf90.pl script which generates these fortran
+# files has no way of handling doxygen documentation. So use sed to
+# insert some documentation lines to suppress warnings.
+pionfatt_mod_2.f90: pionfatt_mod.f90
+	sed -e '/^  integer function put_att_desc_real.*/i !> put real att' \
+            -e '/^  integer function put_att_desc_double.*/i !> put double att' \
+            -e '/^  integer function put_att_desc_int.*/i !> put int att' \
+            -e '/^  integer function put_att_vid_text.*/i !> put text att' \
+            -e '/^  integer function put_att_vid_real.*/i !> put real att' \
+            -e '/^  integer function put_att_vid_double.*/i !> put double att' \
+            -e '/^  integer function put_att_vid_int.*/i !> put int att' \
+            -e '/^  integer function put_att_id_int.*/i !> put int att' \
+            -e '/^  integer function put_att_id_real.*/i !> put att' \
+            -e '/^  integer function put_att_id_double.*/i !> put att' \
+            -e '/^  integer function put_att_id_text.*/i !> put att' \
+            -e '/^  integer function put_att_1d_id_text.*/i !> put att' \
+            -e '/^  integer function put_att_1d_id_text_internal.*/i !> put att' \
+            -e '/^  integer function get_att_id_text.*/i !> get att' \
+            -e '/^  integer function put_att_1d_id_internal_real.*/i !> att' \
+            -e '/^  integer function put_att_1d_id_internal_double.*/i !> att' \
+            -e '/^  integer function put_att_1d_id_internal_int.*/i !> att' \
+            -e '/^  integer function put_att_1d_vid_text.*/i !> att' \
+            -e '/^  integer function put_att_1d_vid_real.*/i !> att' \
+            -e '/^  integer function put_att_1d_vid_double.*/i !> att' \
+            -e '/^  integer function put_att_1d_vid_int.*/i !> att' \
+            -e '/^  integer function get_att_desc_real.*/i !> att' \
+            -e '/^  integer function get_att_desc_double.*/i !> att' \
+            -e '/^  integer function get_att_desc_int.*/i !> att' \
+            -e '/^  integer function get_att_desc_1d_real.*/i !> att' \
+            -e '/^  integer function get_att_desc_1d_double.*/i !> att' \
+            -e '/^  integer function get_att_id_real.*/i !> att' \
+            -e '/^  integer function get_att_id_double.*/i !> att' \
+            -e '/^  integer function get_att_text.*/i !> att' \
+            -e '/^  integer function get_att_real.*/i !> att' \
+            -e '/^  integer function get_att_double.*/i !> att' \
+            -e '/^  integer function get_att_int.*/i !> att' \
+            -e '/^  integer function get_att_1d_id_real.*/i !> att' \
+            -e '/^  integer function get_att_1d_id_int.*/i !> att' \
+            -e '/^  integer function get_att_1d_id_double.*/i !> att' \
+            -e '/^     integer(C_INT) function PIOc_get_att_double.*/i !> att' \
+            -e '/^  integer function pioc_get_att_float.*/i !> att' \
+            -e '/^  integer function pioc_get_att_int.*/i !> att' \
+            -e '/^  integer function pioc_get_att_text.*/i !> att' \
+            -e '/^  integer function pioc_put_att_double.*/i !> att' \
+            -e '/^  integer function pioc_put_att_float.*/i !> att' \
+            -e '/^  integer function pioc_put_att_int.*/i !> att' \
+            -e '/^  integer function pioc_put_att_text.*/i !> att' \
+            $< > $@
+pionfget_mod_2.f90: pionfget_mod.f90
+	sed -e '/^  integer function get_var1_id_real.*/i !> var' \
+            -e '/^  integer function get_var1_id_double.*/i !> var' \
+            -e '/^  integer function get_var1_id_text.*/i !> var' \
+            -e '/^  integer function get_var_0d_real.*/i !> var' \
+            -e '/^  integer function get_var_0d_double.*/i !> var' \
+            -e '/^  integer function get_var_1d_text.*/i !> var' \
+            -e '/^  integer function get_vara_real_internal.*/i !> var' \
+            -e '/^  integer function get_vara_double_internal.*/i !> var' \
+            -e '/^  integer function get_vara_text_internal.*/i !> var' \
+            -e '/^  integer function get_var_1d_int.*/i !> var' \
+            $< > $@
 endif
 
 CLEANFILES = *.mod piodarray.F90 pionfatt_mod.F90 pionfget_mod.F90	\

diff --git a/src/flib/piolib_mod.F90 b/src/flib/piolib_mod.F90
@@ -1151,7 +1151,8 @@ end subroutine init_intercom
 !>
 !! @public
 !! @defgroup PIO_set_hint_grp  PIO_set_hint
-!! @brief set file system hints using mpi_info_set
+
+!> @brief set file system hints using mpi_info_set
 !! @details This is a collective call which expects the following parameters:
 !! @param iosystem @copydoc io_desc_t
 !! @param hint  the string name of the hint to define

diff --git a/src/flib/pionfatt_mod.F90.in b/src/flib/pionfatt_mod.F90.in
@@ -47,10 +47,10 @@ module pionfatt_mod
   !! @brief Reads  an netcdf attribute from a file
   !<
 
+  !> @cond doxygen_cant_handle_so_exclude
   private :: modName
   character(len=*), parameter :: modName='pionfatt_mod'
   interface
-     !> @brief Write a netCDF text attribute.
      integer(C_INT) function PIOc_put_att_text (ncid, varid, name, len, op) &
           bind(C,name="PIOc_put_att_text")
        use iso_c_binding
@@ -143,7 +143,7 @@ module pionfatt_mod
        real(C_DOUBLE), intent(out)   :: op
      end function PIOc_get_att_double
   end interface
-
+  !> @endcond
 
 contains