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

[Kieran Bingham]

Quoting Laurent Pinchart (2024-05-13 13:43:23)
> 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.
> 

I like this. CI is the place to catch it!


Reviewed-by: Kieran Bingham <kieran.bingham at ideasonboard.com>

> 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
>