[PATCH] Documentation: Add option to treat Doxygen warnings as errors

[Laurent Pinchart]

A new Doxygen warning introduced in a recent commit went unnoticed, both
in manual tests and in CI. Unlike C/C++ warnings that are treated as
errors, we don't fail the build with Doxygen warnings. This is due to
the fact that the libcamera documentation compiles cleanly only with quite
recent versions of Doxygen. Enabling the WARN_AS_ERROR Doxygen option
unconditionally could bother many users.

To improve the situation, add a meson option to treat Doxygen warnings
as errors. The option is disabled by default, preserving the current
behaviour, and will be enabled in CI builds.

Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
---
 Documentation/Doxyfile.in | 1 +
 Documentation/meson.build | 1 +
 meson_options.txt         | 5 +++++
 3 files changed, 7 insertions(+)

diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in
index 2be8d47b8419..abafcf6c6c66 100644
--- a/Documentation/Doxyfile.in
+++ b/Documentation/Doxyfile.in
@@ -20,6 +20,7 @@ TOC_INCLUDE_HEADINGS   = 0
 CASE_SENSE_NAMES       = YES
 
 QUIET                  = YES
+WARN_AS_ERROR          = @WARN_AS_ERROR@
 
 INPUT                  = "@TOP_SRCDIR@/include/libcamera" \
                          "@TOP_SRCDIR@/src/ipa/ipu3" \
diff --git a/Documentation/meson.build b/Documentation/meson.build
index 3872e0a8f522..30d395234952 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -15,6 +15,7 @@ if doxygen.found() and dot.found()
     cdata.set('TOP_SRCDIR', meson.project_source_root())
     cdata.set('TOP_BUILDDIR', meson.project_build_root())
     cdata.set('OUTPUT_DIR', meson.current_build_dir())
+    cdata.set('WARN_AS_ERROR', get_option('doc_werror') ? 'YES' : 'NO')
 
     doxygen_predefined = []
     foreach key : config_h.keys()
diff --git a/meson_options.txt b/meson_options.txt
index c61eb55584b5..7aa412491e91 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -20,6 +20,11 @@ option('documentation',
         type : 'feature',
         description : 'Generate the project documentation')
 
+option('doc_werror',
+        type : 'boolean',
+        value : false,
+        description : 'Treat documentation warnings as errors')
+
 option('gstreamer',
         type : 'feature',
         value : 'auto',

base-commit: 3cb20bc2301c03d01a631eb637ab47031d2b91e6
-- 
Regards,

Laurent Pinchart