lkml.org 
[lkml]   [2022]   [Sep]   [12]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else
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

\
 
 \ /
  Last update: 2022-09-12 18:48    [W:0.088 / U:0.144 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site