summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAllen Byrne <50328838+byrnHDF@users.noreply.github.com>2023-10-19 21:58:33 (GMT)
committerGitHub <noreply@github.com>2023-10-19 21:58:33 (GMT)
commit5844f498b03c9da5eb99c6665f4a8ff4663b190f (patch)
treed1f0e2d676ff06300a1de769c2afcc929f734484
parent5672fd817732e6a7fda3886010452bc7c8598cf8 (diff)
downloadhdf5-5844f498b03c9da5eb99c6665f4a8ff4663b190f.zip
hdf5-5844f498b03c9da5eb99c6665f4a8ff4663b190f.tar.gz
hdf5-5844f498b03c9da5eb99c6665f4a8ff4663b190f.tar.bz2
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
-rw-r--r--CMakeLists.txt7
-rw-r--r--configure.ac25
-rw-r--r--doxygen/CMakeLists.txt1
-rw-r--r--doxygen/Doxyfile.in2
-rw-r--r--release_docs/INSTALL_CMake.txt1
-rw-r--r--release_docs/RELEASE.txt12
6 files changed, 47 insertions, 1 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 5b76afe..c440c58 100644
--- a/CMakeLists.txt
+++ b/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 ()
diff --git a/configure.ac b/configure.ac
index 02c47d6..44ab43a 100644
--- a/configure.ac
+++ b/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
diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt
index 7bfbe74..8fe3b77 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 b24b9f9..464e09a 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 281c9a1..c837d1c 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 83c20b0..d2411d9 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)
+ * --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