Documentation: Add option to treat Doxygen warnings as errors

20044 diff mbox series

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@ideasonboard.com>
---
 Documentation/Doxyfile.in | 1 +
 Documentation/meson.build | 1 +
 meson_options.txt         | 5 +++++
 3 files changed, 7 insertions(+)


base-commit: 3cb20bc2301c03d01a631eb637ab47031d2b91e6

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@ideasonboard.com>

> Signed-off-by: Laurent Pinchart <laurent.pinchart@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
>