Messages in this thread | | | Date | Mon, 12 Sep 2022 18:47:56 +0200 | From | Mauro Carvalho Chehab <> | Subject | Re: [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
| |