Add an option to disable doxygen warn as error (#3708)

Add for both CMake and the Autotools

* HDF5_ENABLE_DOXY_WARNINGS: ON/OFF (Default: ON)
* --enable-doxygen-errors: enable/disable (Default: enable)

The default will fail compile if the doxygen parsing generates warnings.
The option can be disabled if certain versions of doxygen have parsing
issues. i.e. 1.9.5, 1.9.8.

Fixes #3398

CMakeLists.txt

@@ -959,6 +959,13 @@ if (HDF5_BUILD_DOC AND EXISTS "${HDF5_DOXYGEN_DIR}" AND IS_DIRECTORY "${HDF5_DOX
 # check if Doxygen is installed
   find_package(Doxygen)
   if (DOXYGEN_FOUND)
+    option (HDF5_ENABLE_DOXY_WARNINGS "Enable fail if doxygen parsing has warnings." ON)
+    mark_as_advanced (HDF5_ENABLE_DOXY_WARNINGS)
+    if (HDF5_ENABLE_DOXY_WARNINGS)
+      set (HDF5_DOXY_WARNINGS "FAIL_ON_WARNINGS")
+    else ()
+      set (HDF5_DOXY_WARNINGS "NO")
+    endif ()
     message(STATUS "Doxygen version: ${DOXYGEN_VERSION}")
     add_subdirectory (doxygen)
   else ()

configure.ac

@@ -1207,6 +1207,30 @@ AC_ARG_ENABLE([doxygen],
 
 AC_MSG_RESULT([$HDF5_DOXYGEN])
 
+## Check if they would like to enable doxygen warnings as errors
+##
+
+## This needs to be exposed for the library info file.
+AC_SUBST([HDF5_DOXY_WARNINGS])
+
+## Default is to consider doxygen warnings as errors
+DOXY_ERR=yes
+
+AC_MSG_CHECKING([if doxygen warnings as errors is enabled])
+
+AC_ARG_ENABLE([doxygen-errors],
+              [AS_HELP_STRING([--enable-doxygen-errors],
+                              [Error on HDF5 doxygen warnings [default=yes]])],
+              [DOXY_ERR=$enableval])
+
+if test "X$DOXY_ERR" = "Xyes"; then
+    HDF5_DOXY_WARNINGS="FAIL_ON_WARNINGS"
+else
+    HDF5_DOXY_WARNINGS="NO"
+
+fi
+AC_MSG_RESULT([$HDF5_DOXY_WARNINGS])
+
 if test "X$HDF5_DOXYGEN" = "Xyes"; then
   DX_DOXYGEN_FEATURE(ON)
   DX_DOT_FEATURE(OFF)
@@ -1269,6 +1293,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then
   DOXYGEN_STRIP_FROM_PATH='$(SRCDIR)'
   DOXYGEN_STRIP_FROM_INC_PATH='$(SRCDIR)'
   DOXYGEN_PREDEFINED='H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD H5_DOXYGEN H5_HAVE_SUBFILING_VFD H5_HAVE_IOC_VFD H5_HAVE_MIRROR_VFD'
+  DOXYGEN_WARN_AS_ERROR=${HDF5_DOXY_WARNINGS}
 
   DX_INIT_DOXYGEN([HDF5], [./doxygen/Doxyfile], [hdf5lib_docs])
 fi

doxygen/CMakeLists.txt

@@ -30,6 +30,7 @@ if (DOXYGEN_FOUND)
   set (DOXYGEN_STRIP_FROM_PATH ${HDF5_SOURCE_DIR})
   set (DOXYGEN_STRIP_FROM_INC_PATH ${HDF5_SOURCE_DIR})
   set (DOXYGEN_PREDEFINED "H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD H5_DOXYGEN H5_HAVE_SUBFILING_VFD H5_HAVE_IOC_VFD H5_HAVE_MIRROR_VFD")
+  set (DOXYGEN_WARN_AS_ERROR ${HDF5_DOXY_WARNINGS})
 
 # This configure and individual custom targets work together
   # Replace variables inside @@ with the current values

doxygen/Doxyfile.in

@@ -625,7 +625,7 @@ WARN_NO_PARAMDOC       = NO
 # a warning is encountered.
 # The default value is: NO.
 
-WARN_AS_ERROR          = FAIL_ON_WARNINGS
+WARN_AS_ERROR          = @DOXYGEN_WARN_AS_ERROR@
 
 # The WARN_FORMAT tag determines the format of the warning messages that doxygen
 # can produce. The string should contain the $file, $line, and $text tags, which

release_docs/INSTALL_CMake.txt

@@ -859,6 +859,7 @@ HDF5_ENABLE_ANALYZER_TOOLS     "enable the use of Clang tools"
 HDF5_ENABLE_SANITIZERS         "execute the Clang sanitizer"                        OFF
 HDF5_ENABLE_FORMATTERS         "format source files"                                OFF
 HDF5_DIMENSION_SCALES_NEW_REF  "Use new-style references with dimension scale APIs" OFF
+HDF5_ENABLE_DOXY_WARNINGS      "Enable fail if doxygen parsing has warnings."       ON
 
 ---------------- HDF5 Advanced Test Options ---------------------
 if (BUILD_TESTING)

release_docs/RELEASE.txt

@@ -47,6 +47,18 @@ New Features
 
     Configuration:
     -------------
+    - Added new options for CMake and Autotools to control the Doxygen
+      warnings as errors setting.
+
+        * HDF5_ENABLE_DOXY_WARNINGS: ON/OFF (Default: ON)
+        * --enable-doxygen-errors: enable/disable (Default: enable)
+
+      The default will fail compile if the doxygen parsing generates warnings.
+      The option can be disabled if certain versions of doxygen have parsing
+      issues. i.e. 1.9.5, 1.9.8.
+
+      Addresses GitHub issue #3398
+
     - Added support for AOCC and classic Flang w/ the Autotools
 
       * Adds a config/clang-fflags options file to support Flang