Re: [Intel-gfx] [PATCH] drm/i915: enable kernel-doc warnings for CONFIG_DRM_I915_WERROR=y

[Jani Nikula <jani.nikula@intel.com>]

On Fri, 31 Mar 2023, Jani Nikula <jani.nikula@intel.com> wrote:
> Increase awareness of kernel-doc issues by enabling doc check locally
> when W= is *not* specified on the make command-line, but
> CONFIG_DRM_I915_WERROR=y is enabled.
>
> Once the warnings have been fixed, we can pass -Werror to kernel-doc
> locally, and fail the build when there are kernel-doc warnings in i915.
>
> Cc: Masahiro Yamada <masahiroy@kernel.org>
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>
> ---
>
> Masahiro, is this an awful hack to do in our local Makefile?
>
> Note that we do try to avoid anyone outside of i915 developers enabling
> CONFIG_DRM_I915_WERROR=y.
>
> Any other and cleaner ways of achieving this, without using W= on the
> entire kernel?
>
> On that note, it would be nice to be able to enable W= on a subdir
> alone.

To elaborate, we add a bunch of W=1 style warnings in our local
Makefile, and try to maintain a high standard with them, but it's a bit
tedious to duplicate what's in scripts/Makefile.extrawarn. However that
doesn't seem to be easily reusable for subdir-ccflags-y.

We also add -Werror for CONFIG_DRM_I915_WERROR=y, and have our
developers and CI use that so we don't slip.

As to this patch, we'd like to do the same for kernel-doc. And,
hopefully, also enable -Werror for kernel-doc.

BR,
Jani.


> ---
>  drivers/gpu/drm/i915/Makefile | 8 ++++++++
>  1 file changed, 8 insertions(+)
>
> diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile
> index 057ef22fa9c6..13d7040801bf 100644
> --- a/drivers/gpu/drm/i915/Makefile
> +++ b/drivers/gpu/drm/i915/Makefile
> @@ -369,6 +369,14 @@ include $(src)/gvt/Makefile
>  obj-$(CONFIG_DRM_I915) += i915.o
>  obj-$(CONFIG_DRM_I915_GVT_KVMGT) += kvmgt.o
>  
> +# kernel-doc test
> +#
> +# Enable locally for CONFIG_DRM_I915_WERROR=y if not already enabled.
> +# See scripts/Makefile.build
> +ifeq ($(KBUILD_EXTRA_WARN)$(CONFIG_DRM_I915_WERROR),y)
> +    cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $<
> +endif
> +
>  # header test
>  
>  # exclude some broken headers from the test coverage

-- 
Jani Nikula, Intel Open Source Graphics Center