From: Matt Roper <matthew.d.roper@intel.com>
To: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: "Rodrigo Vivi" <rodrigo.vivi@intel.com>,
"Ville Syrjälä" <ville.syrjala@linux.intel.com>,
"Alan Previn" <alan.previn.teres.alexis@intel.com>,
"Andi Shyti" <andi.shyti@linux.intel.com>,
"Ashutosh Dixit" <ashutosh.dixit@intel.com>,
"Chris Wilson" <chris@chris-wilson.co.uk>,
"Daniel Vetter" <daniel@ffwll.ch>,
"Daniele Ceraolo Spurio" <daniele.ceraolospurio@intel.com>,
"David Airlie" <airlied@linux.ie>,
"Imre Deak" <imre.deak@intel.com>,
"Jani Nikula" <jani.nikula@linux.intel.com>,
"John Harrison" <John.C.Harrison@intel.com>,
"Joonas Lahtinen" <joonas.lahtinen@linux.intel.com>,
"Lucas De Marchi" <lucas.demarchi@intel.com>,
"Matthew Auld" <matthew.auld@intel.com>,
"Matthew Brost" <matthew.brost@intel.com>,
"Stanislav Lisovskiy" <stanislav.lisovskiy@intel.com>,
"Tomas Winkler" <tomas.winkler@intel.com>,
"Tvrtko Ursulin" <tvrtko.ursulin@linux.intel.com>,
"Umesh Nerlige Ramappa" <umesh.nerlige.ramappa@intel.com>,
dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else
Date: Mon, 12 Sep 2022 10:19:04 -0700 [thread overview]
Message-ID: <Yx9qCCmxnSM06CgH@mdroper-desk1.amr.corp.intel.com> (raw)
In-Reply-To: <20220912184756.61492ad1@coco.lan>
On Mon, Sep 12, 2022 at 06:47:56PM +0200, Mauro Carvalho Chehab wrote:
> 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.
Right, what we have today is incomplete/incorrect. But I think we
should be fixing that by adding the missing documentation on the
structure, rather than giving up and removing the kerneldoc. The end
goal should be to have proper generated documentation, not just silence
the warnings while leaving the actual output incomplete.
Matt
>
> 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
--
Matt Roper
Graphics Software Engineer
VTT-OSGC Platform Enablement
Intel Corporation
next prev parent reply other threads:[~2022-09-12 17:19 UTC|newest]
Thread overview: 54+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-09-09 7:34 [PATCH v3 00/37] drm/i915: fix kernel-doc issues Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 01/37] drm/i915: fix kernel-doc trivial warnings on i915/*.[ch] files Mauro Carvalho Chehab
2022-09-16 14:03 ` [Intel-gfx] " Gwan-gyeong Mun
2022-09-26 9:19 ` Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 02/37] drm/i915: display: fix kernel-doc markup warnings Mauro Carvalho Chehab
2022-09-16 12:35 ` [Intel-gfx] " Gwan-gyeong Mun
2022-09-09 7:34 ` [PATCH v3 03/37] drm/i915: gt: fix some Kernel-doc issues Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 04/37] drm/i915: gvt: fix kernel-doc trivial warnings Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 05/37] drm/i915: gem: fix some Kernel-doc issues Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 06/37] drm/i915: intel_wakeref.h: fix some kernel-doc markups Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 07/37] drm/i915: i915_gem_ttm: fix a kernel-doc markup Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 08/37] drm/i915: i915_gem_ttm_pm.c: fix kernel-doc markups Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 09/37] drm/i915: gem: add kernel-doc description for some function parameters Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 10/37] drm/i915: i915_gpu_error.c: document dump_flags Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 11/37] drm/i915: document kernel-doc trivial issues Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 12/37] drm/i915: intel_dp_link_training.c: fix kernel-doc markup Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 13/37] drm/i915: intel_fb: fix a kernel-doc issue with Sphinx Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 14/37] drm/i915: skl_scaler: fix return value kernel-doc markup Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 15/37] drm/i915: intel_pm.c: fix some ascii artwork at kernel-doc Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 16/37] drm/i915: i915_gem_region.h: fix i915_gem_apply_to_region_ops doc Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 17/37] drm/i915: i915_gem_wait.c: fix a kernel-doc markup Mauro Carvalho Chehab
2022-09-12 1:22 ` Andi Shyti
2022-09-09 7:34 ` [PATCH v3 18/37] drm/i915: fix i915_gem_ttm_move.c DOC: markup Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else Mauro Carvalho Chehab
2022-09-12 1:23 ` Andi Shyti
2022-09-12 15:09 ` Matt Roper
2022-09-12 16:47 ` Mauro Carvalho Chehab
2022-09-12 17:19 ` Matt Roper [this message]
2022-09-26 8:25 ` [Intel-gfx] " Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 20/37] drm/i915: dvo_ch7xxx.c: use SPDX header Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 21/37] drm/i915: dvo_sil164.c: " Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 22/37] drm/i915: i915_vma_resource.c: fix some kernel-doc markups Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 23/37] drm/i915: i915_gem.c fix a kernel-doc issue Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 24/37] drm/i915: i915_scatterlist.h: fix some kernel-doc markups Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 25/37] drm/i915: i915_deps: use a shorter title markup Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 26/37] docs: gpu: i915.rst: display: add kernel-doc markups Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 27/37] docs: gpu: i915.rst: gt: add more " Mauro Carvalho Chehab
2022-09-09 9:06 ` [Intel-gfx] " Rodrigo Vivi
2022-09-26 9:45 ` Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 28/37] docs: gpu: i915.rst: GuC: " Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 29/37] docs: gpu: i915.rst: GVT: " Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 30/37] docs: gpu: i915.rst: PM: " Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 31/37] docs: gpu: i915.rst: GEM/TTM: " Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 32/37] docs: gpu: i915.rst: add the remaining kernel-doc markup files Mauro Carvalho Chehab
2022-09-09 9:10 ` [Intel-gfx] " Rodrigo Vivi
2022-09-09 7:34 ` [PATCH v3 33/37] drm/i915 i915_gem_object_types.h: document struct i915_lut_handle Mauro Carvalho Chehab
2022-09-12 1:25 ` Andi Shyti
2022-09-09 7:34 ` [PATCH v3 34/37] drm/i915: document struct drm_i915_gem_object Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 35/37] drm/i915: add descriptions for some RPM macros at intel_gt_pm.h Mauro Carvalho Chehab
2022-09-09 9:12 ` Rodrigo Vivi
2022-09-12 1:27 ` Andi Shyti
2022-09-09 7:34 ` [PATCH v3 36/37] drm/i915: add GuC functions to the documentation Mauro Carvalho Chehab
2022-09-09 7:34 ` [PATCH v3 37/37] drm/i915: be consistent with kernel-doc function declaration Mauro Carvalho Chehab
2022-09-09 9:13 ` Rodrigo Vivi
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=Yx9qCCmxnSM06CgH@mdroper-desk1.amr.corp.intel.com \
--to=matthew.d.roper@intel.com \
--cc=John.C.Harrison@intel.com \
--cc=airlied@linux.ie \
--cc=alan.previn.teres.alexis@intel.com \
--cc=andi.shyti@linux.intel.com \
--cc=ashutosh.dixit@intel.com \
--cc=chris@chris-wilson.co.uk \
--cc=daniel@ffwll.ch \
--cc=daniele.ceraolospurio@intel.com \
--cc=dri-devel@lists.freedesktop.org \
--cc=imre.deak@intel.com \
--cc=intel-gfx@lists.freedesktop.org \
--cc=jani.nikula@linux.intel.com \
--cc=joonas.lahtinen@linux.intel.com \
--cc=linux-kernel@vger.kernel.org \
--cc=lucas.demarchi@intel.com \
--cc=matthew.auld@intel.com \
--cc=matthew.brost@intel.com \
--cc=mchehab@kernel.org \
--cc=rodrigo.vivi@intel.com \
--cc=stanislav.lisovskiy@intel.com \
--cc=tomas.winkler@intel.com \
--cc=tvrtko.ursulin@linux.intel.com \
--cc=umesh.nerlige.ramappa@intel.com \
--cc=ville.syrjala@linux.intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®