From d0cffca636620342c0323272331602fe51932ef1 Mon Sep 17 00:00:00 2001
From: Allen Byrne <byrn@hdfgroup.org>
Date: Wed, 18 Oct 2023 13:18:39 -0500
Subject: [PATCH] GH issue 3398 - option to disable doxygen warn as error

---
 CMakeLists.txt                 |  7 +++++++
 configure.ac                   | 19 +++++++++++++++++++
 doxygen/CMakeLists.txt         |  1 +
 doxygen/Doxyfile.in            |  2 +-
 release_docs/INSTALL_CMake.txt |  1 +
 release_docs/RELEASE.txt       | 12 ++++++++++++
 6 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 6aa467d110b..27b2a8cbfbe 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -952,6 +952,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_USE_FOLDERS)
+    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 ()
diff --git a/configure.ac b/configure.ac
index 02c47d61002..9f1053bb28a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1207,6 +1207,24 @@ 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 not build DOXYGEN
+HDF5_DOXY_WARNINGS=no
+
+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]])],
+              [HDF5_DOXY_WARNINGS=$enableval])
+
+AC_MSG_RESULT([$HDF5_DOXY_WARNINGS])
+
 if test "X$HDF5_DOXYGEN" = "Xyes"; then
   DX_DOXYGEN_FEATURE(ON)
   DX_DOT_FEATURE(OFF)
@@ -1269,6 +1287,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
diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt
index 7bfbe74906a..8fe3b771103 100644
--- a/doxygen/CMakeLists.txt
+++ b/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
diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in
index b24b9f9e509..464e09a7201 100644
--- a/doxygen/Doxyfile.in
+++ b/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
diff --git a/release_docs/INSTALL_CMake.txt b/release_docs/INSTALL_CMake.txt
index 281c9a18f6c..c837d1c4e02 100644
--- a/release_docs/INSTALL_CMake.txt
+++ b/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)
diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt
index b50fe611213..2267fbdc952 100644
--- a/release_docs/RELEASE.txt
+++ b/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)
+        * 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