Re: [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else

[Mauro Carvalho Chehab <mchehab@kernel.org>]

Hi Matt,

Em Mon, 12 Sep 2022 08:09:57 -0700
Matt Roper <matthew.d.roper@intel.com> escreveu:

> > --- a/drivers/gpu/drm/i915/gt/intel_context_types.h
> > +++ b/drivers/gpu/drm/i915/gt/intel_context_types.h  
> 
> Several of the comments in this file do appear to be kerneldoc (in fact
> kerneldoc that was specifically requested during code review at
> https://patchwork.freedesktop.org/patch/448456/#comment_804252) and this
> file is included from Documentation/gpu/i915.rst, so I think some of
> these changes might be moving in the wrong direction.  Should we instead
> focus on fixing up the comments that aren't quite formatted properly?

Those *appear* to be kernel-doc markups, but they aren't, because
the structs themselves are not properly marked. See, for instance
struct intel_context.

scripts/kerneldoc will *only* consider what's there as a proper
comment if you add:

	/**
	 * struct intel_context - describes an i915 context
	 * <add a proper description for it>
	 */
	struct intel_context {
		union {
			/** @ref: a kernel object reference */
	                struct kref ref; /* no kref_get_unless_zero()! */
			/** @rcu: a rcu header */
	                struct rcu_head rcu;
	        };
		...
	}

Describing all fields inside the struct. Just placing
	/** something */
on some random places in the middle doesn't make it a kernel-doc.

If you actually run kernel-doc in Werror mode:

	./scripts/kernel-doc -Werror -sphinx-version 2.4.4 drivers/gpu/drm/i915/gt/intel_context_types.h | echo "ERROR!"
	ERROR!
	drivers/gpu/drm/i915/gt/intel_context_types.h:1: warning: no structured comments found
	1 warnings as Errors

you'll see that this is currently broken.

Thanks,
Mauro