From: Mauro Carvalho Chehab <mauro.chehab@linux.intel.com>
To: Rodrigo Vivi <rodrigo.vivi@intel.com>
Cc: Jonathan Corbet <corbet@lwn.net>, David Airlie <airlied@linux.ie>,
intel-gfx@lists.freedesktop.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org, dri-devel@lists.freedesktop.org,
Thomas Zimmermann <tzimmermann@suse.de>,
Mauro Carvalho Chehab <mchehab@kernel.org>
Subject: Re: [Intel-gfx] [PATCH v2 35/39] docs: gpu: i915.rst: add the remaining kernel-doc markup files
Date: Tue, 6 Sep 2022 21:43:30 +0200 [thread overview]
Message-ID: <20220906214323.3d3a0db4@maurocar-mobl2> (raw)
In-Reply-To: <YvI1CbsIZIG7FVBP@intel.com>
On Tue, 9 Aug 2022 06:20:57 -0400
Rodrigo Vivi <rodrigo.vivi@intel.com> wrote:
> On Wed, Jul 13, 2022 at 09:12:23AM +0100, Mauro Carvalho Chehab wrote:
> > There are other files with kernel-doc markups:
> >
> > $ git grep -l "/\*\*" $(git ls-files|grep drivers/gpu/drm/i915/) >kernel-doc-files
> > $ for i in $(cat kernel-doc-files); do if [ "$(git grep $i Documentation/)" == "" ]; then echo "$i"; fi; done >aaa
> >
> > Add them to i915.rst as well.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> > ---
> >
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/
> >
> > Documentation/gpu/i915.rst | 87 ++++++++++++++++++++++++++++++++++++++
> > 1 file changed, 87 insertions(+)
> >
> > diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> > index 974754586be8..6bb50edc6d79 100644
> > --- a/Documentation/gpu/i915.rst
> > +++ b/Documentation/gpu/i915.rst
> > @@ -13,6 +13,11 @@ Core Driver Infrastructure
> > This section covers core driver infrastructure used by both the display
> > and the GEM parts of the driver.
> >
> > +Core driver
> > +-----------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_driver.c
> > +
> > Runtime Power Management
> > ------------------------
> >
> > @@ -29,6 +34,10 @@ Runtime Power Management
> >
> > .. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
> >
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_wakeref.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_active.h
>
> not sure if this belongs to this group...
>
> > +
> > Interrupt Handling
> > ------------------
> >
> > @@ -44,6 +53,28 @@ Interrupt Handling
> > .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
> > :functions: intel_runtime_pm_enable_interrupts
> >
> > +Error handling
> > +--------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_gpu_error.c
>
> not sure if this gt hang stuff deserves a separated section
> alone and if the name is the best one....
>
> > +
> > +Memory Handling
> > +---------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_mm.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_memory_region.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_memcpy.c
> > +
> > Intel GVT-g Guest Support(vGPU)
>
> ^ missing space
>
> > -------------------------------
> >
> > @@ -109,6 +140,54 @@ Workarounds
> > .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
> > :doc: Hardware workarounds
> >
> > +32-bits compatible ioctl Logic
> > +------------------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_ioc32.c
> > +
> > +Scatterlist handling
> > +--------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.c
> > +
> > +i915 request
> > +------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_request.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_request.c
> > +
> > +Ancillary routines
>
> maybe simply have an "Others" section and put everything
> that has only one item like the gpu hang one?
OK!
>
> > +------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_device_info.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_params.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_sw_fence_work.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_syncmap.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_pcode.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_reg_defs.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.h
> > +
> > +
> > +PXP
>
> Protected Xe Path (PXP)
>
>
> > +---
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_irq.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_tee.c
> > +
> > Display Hardware Handling
> > =========================
> >
> > @@ -618,6 +697,12 @@ Protected Objects
> > Table Manager (TTM)
> > -------------------
> >
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_region_ttm.c
> > +
> > .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.c
> >
> > .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.h
> > @@ -627,6 +712,8 @@ Table Manager (TTM)
> > Graphics Execution Manager (GEM)
> > --------------------------------
> >
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c
> > +
> > .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_create.c
> >
> > .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_domain.c
>
> in many cases I see only the .h or only the .c... why is that?
> wouldn't be better already put both in all the cases?
No. Adding kernel-doc files that doesn't contain any markups
will produce warnings.
We're working hard upstream to have a zero-warnings policy for
documentation.
Regards,
Mauro
next prev parent reply other threads:[~2022-09-06 19:53 UTC|newest]
Thread overview: 92+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-07-13 8:11 [PATCH v2 00/39] drm/i915: fix kernel-doc issues Mauro Carvalho Chehab
2022-07-13 8:11 ` [PATCH v2 01/39] drm/i915/gvt: Fix kernel-doc for intel_gvt_switch_mmio() Mauro Carvalho Chehab
2022-07-13 21:54 ` Rodrigo Vivi
2022-07-13 22:00 ` Rodrigo Vivi
2022-07-14 8:50 ` [Intel-gfx] " Mauro Carvalho Chehab
2022-07-13 8:11 ` [PATCH v2 02/39] drm/i915/gvt: Fix kernel-doc for intel_vgpu_default_mmio_write Mauro Carvalho Chehab
2022-07-13 21:55 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:11 ` [PATCH v2 03/39] drm/i915/gvt: Fix kernel-doc for intel_vgpu_*_resource() Mauro Carvalho Chehab
2022-07-13 22:02 ` Rodrigo Vivi
2022-07-13 8:11 ` [PATCH v2 04/39] drm/i915: fix kernel-doc trivial warnings on i915/*.[ch] files Mauro Carvalho Chehab
2022-07-13 22:02 ` Rodrigo Vivi
2022-07-13 8:11 ` [PATCH v2 05/39] drm/i915: display: fix kernel-doc markup warnings Mauro Carvalho Chehab
2022-07-13 22:05 ` Rodrigo Vivi
2022-07-14 9:56 ` [Intel-gfx] " Mauro Carvalho Chehab
2022-07-13 8:11 ` [PATCH v2 06/39] drm/i915: gt: fix some Kernel-doc issues Mauro Carvalho Chehab
2022-07-13 22:07 ` [Intel-gfx] " Rodrigo Vivi
2022-07-14 10:01 ` Mauro Carvalho Chehab
2022-07-13 8:11 ` [PATCH v2 07/39] drm/i915: gvt: fix kernel-doc trivial warnings Mauro Carvalho Chehab
2022-07-13 22:08 ` Rodrigo Vivi
2022-07-14 4:23 ` Zhenyu Wang
2022-07-13 8:11 ` [PATCH v2 08/39] drm/i915: gem: fix some Kernel-doc issues Mauro Carvalho Chehab
2022-07-13 8:51 ` Das, Nirmoy
2022-07-13 8:11 ` [PATCH v2 09/39] drm/i915: intel_wakeref.h: fix some kernel-doc markups Mauro Carvalho Chehab
2022-07-13 22:09 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:11 ` [PATCH v2 10/39] drm/i915: i915_gem_ttm: fix a kernel-doc markup Mauro Carvalho Chehab
2022-07-13 9:02 ` Das, Nirmoy
2022-07-13 8:11 ` [PATCH v2 11/39] drm/i915: i915_gem_ttm_pm.c: fix kernel-doc markups Mauro Carvalho Chehab
2022-08-09 10:23 ` Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 12/39] drm/i915: gem: add kernel-doc description for some function parameters Mauro Carvalho Chehab
2022-07-13 9:09 ` Das, Nirmoy
2022-07-13 8:12 ` [PATCH v2 13/39] drm/i915: i915_gpu_error.c: document dump_flags Mauro Carvalho Chehab
2022-07-15 21:38 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 14/39] drm/i915: document kernel-doc trivial issues Mauro Carvalho Chehab
2022-07-15 21:31 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 15/39] drm/i915: intel_dp_link_training.c: fix kernel-doc markup Mauro Carvalho Chehab
2022-08-09 9:51 ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 18:53 ` Mauro Carvalho Chehab
2022-07-13 8:12 ` [PATCH v2 16/39] drm/i915: intel_fb: fix a kernel-doc issue with Sphinx Mauro Carvalho Chehab
2022-07-15 21:40 ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 18:58 ` Mauro Carvalho Chehab
2022-07-13 8:12 ` [PATCH v2 17/39] drm/i915: skl_scaler: fix return value kernel-doc markup Mauro Carvalho Chehab
2022-07-15 21:42 ` Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 18/39] drm/i915: intel_pm.c: fix some ascii artwork at kernel-doc Mauro Carvalho Chehab
2022-08-09 9:55 ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 19:17 ` Mauro Carvalho Chehab
2022-07-13 8:12 ` [PATCH v2 19/39] drm/i915: i915_gem_region.h: fix i915_gem_apply_to_region_ops doc Mauro Carvalho Chehab
2022-08-09 9:59 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 20/39] drm/i915: i915_gem_wait.c: fix a kernel-doc markup Mauro Carvalho Chehab
2022-07-15 21:25 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 21/39] drm/i915: fix i915_gem_ttm_move.c DOC: markup Mauro Carvalho Chehab
2022-07-15 21:41 ` Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 22/39] drm/i915: stop using kernel-doc markups for something else Mauro Carvalho Chehab
2022-07-15 21:34 ` Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 23/39] drm/i915: dvo_ch7xxx.c: use SPDX header Mauro Carvalho Chehab
2022-07-15 21:41 ` Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 24/39] drm/i915: dvo_sil164.c: " Mauro Carvalho Chehab
2022-07-15 21:35 ` Rodrigo Vivi
2022-07-15 22:16 ` Joe Perches
2022-07-18 11:38 ` [Intel-gfx] " Mauro Carvalho Chehab
2022-07-13 8:12 ` [PATCH v2 25/39] drm/i915: i915_vma_resource.c: fix some kernel-doc markups Mauro Carvalho Chehab
2022-07-15 21:32 ` Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 26/39] drm/i915: i915_gem.c fix a kernel-doc issue Mauro Carvalho Chehab
2022-07-15 21:26 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 27/39] drm/i915: i915_scatterlist.h: fix some kernel-doc markups Mauro Carvalho Chehab
2022-07-15 21:33 ` Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 28/39] drm/i915: i915_deps: use a shorter title markup Mauro Carvalho Chehab
2022-07-15 21:32 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 29/39] docs: gpu: i915.rst: display: add kernel-doc markups Mauro Carvalho Chehab
2022-08-09 9:57 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 30/39] docs: gpu: i915.rst: gt: add more " Mauro Carvalho Chehab
2022-08-09 10:01 ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 19:35 ` Mauro Carvalho Chehab
2022-07-13 8:12 ` [PATCH v2 31/39] docs: gpu: i915.rst: GuC: " Mauro Carvalho Chehab
2022-08-09 10:12 ` Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 32/39] docs: gpu: i915.rst: GVT: " Mauro Carvalho Chehab
2022-08-09 9:56 ` Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 33/39] docs: gpu: i915.rst: PM: " Mauro Carvalho Chehab
2022-08-09 10:03 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 34/39] docs: gpu: i915.rst: GEM/TTM: " Mauro Carvalho Chehab
2022-08-09 10:02 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 35/39] docs: gpu: i915.rst: add the remaining kernel-doc markup files Mauro Carvalho Chehab
2022-08-09 10:20 ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 19:43 ` Mauro Carvalho Chehab [this message]
2022-07-13 8:12 ` [PATCH v2 36/39] drm/i915 i915_gem_object_types.h: document struct i915_lut_handle Mauro Carvalho Chehab
2022-08-09 10:09 ` Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 37/39] drm/i915: document struct drm_i915_gem_object Mauro Carvalho Chehab
2022-08-09 10:08 ` [Intel-gfx] " Rodrigo Vivi
2022-07-13 8:12 ` [PATCH v2 38/39] drm/i915: add descriptions for some RPM macros at intel_gt_pm.h Mauro Carvalho Chehab
2022-08-09 10:12 ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 19:47 ` Mauro Carvalho Chehab
2022-07-13 8:12 ` [PATCH v2 39/39] drm/i915: add GuC functions to the documentation Mauro Carvalho Chehab
2022-08-09 10: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=20220906214323.3d3a0db4@maurocar-mobl2 \
--to=mauro.chehab@linux.intel.com \
--cc=airlied@linux.ie \
--cc=corbet@lwn.net \
--cc=dri-devel@lists.freedesktop.org \
--cc=intel-gfx@lists.freedesktop.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab@kernel.org \
--cc=rodrigo.vivi@intel.com \
--cc=tzimmermann@suse.de \
/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;
as well as URLs for NNTP newsgroup(s).