From: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com> To: Sean Anderson <sean.anderson@linux.dev>, Randy Dunlap <rdunlap@infradead.org> Cc: Michal Simek <michal.simek@amd.com>, David Airlie <airlied@gmail.com>, linux-kernel@vger.kernel.org, Daniel Vetter <daniel@ffwll.ch>, linux-arm-kernel@lists.infradead.org, Laurent Pinchart <laurent.pinchart@ideasonboard.com>, Maarten Lankhorst <maarten.lankhorst@linux.intel.com>, Maxime Ripard <mripard@kernel.org>, Thomas Zimmermann <tzimmermann@suse.de>, dri-devel@lists.freedesktop.org Subject: Re: [PATCH v2 1/8] drm: xlnx: Fix kerneldoc Date: Fri, 22 Mar 2024 07:50:56 +0200 [thread overview] Message-ID: <19d6da67-f9a6-4e01-a956-3b60f0ebf769@ideasonboard.com> (raw) In-Reply-To: <2c38ac1c-cc0e-43b3-86d3-5b6a2f00f9e7@linux.dev> On 21/03/2024 17:33, Sean Anderson wrote: > On 3/20/24 02:05, Randy Dunlap wrote: >> >> >> On 3/19/24 22:42, Tomi Valkeinen wrote: >>> On 20/03/2024 00:51, Sean Anderson wrote: >>>> Fix a few errors in the kerneldoc. Mostly this addresses missing/renamed >>>> members. >>>> >>>> Signed-off-by: Sean Anderson <sean.anderson@linux.dev> >>>> --- >>>> >>>> Changes in v2: >>>> - New >>>> >>>> drivers/gpu/drm/xlnx/zynqmp_disp.c | 6 +++--- >>>> drivers/gpu/drm/xlnx/zynqmp_dpsub.h | 1 + >>>> drivers/gpu/drm/xlnx/zynqmp_kms.h | 4 ++-- >>>> 3 files changed, 6 insertions(+), 5 deletions(-) >>>> >>>> diff --git a/drivers/gpu/drm/xlnx/zynqmp_disp.c b/drivers/gpu/drm/xlnx/zynqmp_disp.c >>>> index 407bc07cec69..f79bf3fb8110 100644 >>>> --- a/drivers/gpu/drm/xlnx/zynqmp_disp.c >>>> +++ b/drivers/gpu/drm/xlnx/zynqmp_disp.c >>>> @@ -128,9 +128,9 @@ struct zynqmp_disp_layer { >>>> * struct zynqmp_disp - Display controller >>>> * @dev: Device structure >>>> * @dpsub: Display subsystem >>>> - * @blend.base: Register I/O base address for the blender >>>> - * @avbuf.base: Register I/O base address for the audio/video buffer manager >>>> - * @audio.base: Registers I/O base address for the audio mixer >>>> + * @blend: Register I/O base address for the blender >>>> + * @avbuf: Register I/O base address for the audio/video buffer manager >>>> + * @audio: Registers I/O base address for the audio mixer >>> >>> Afaics, the kernel doc guide: >>> >>> https://docs.kernel.org/doc-guide/kernel-doc.html#nested-structs-unions >>> >>> says that the current version is correct. Or is the issue that while, say, 'base' is documented, 'blend' was not? >> >> Hi, >> >> I would do it more like so: >> >> --- >> drivers/gpu/drm/xlnx/zynqmp_disp.c | 3 +++ >> 1 file changed, 3 insertions(+) >> >> diff -- a/drivers/gpu/drm/xlnx/zynqmp_disp.c b/drivers/gpu/drm/xlnx/zynqmp_disp.c >> --- a/drivers/gpu/drm/xlnx/zynqmp_disp.c >> +++ b/drivers/gpu/drm/xlnx/zynqmp_disp.c >> @@ -128,8 +128,11 @@ struct zynqmp_disp_layer { >> * struct zynqmp_disp - Display controller >> * @dev: Device structure >> * @dpsub: Display subsystem >> + * @blend: blender iomem info >> * @blend.base: Register I/O base address for the blender >> + * @avbuf: audio/video buffer iomem info >> * @avbuf.base: Register I/O base address for the audio/video buffer manager >> + * @audio: audio mixer iomem info >> * @audio.base: Registers I/O base address for the audio mixer >> * @layers: Layers (planes) >> */ >> >> >> but in my testing, Sean's way or my way result in no warning/errors. >> > > The specific errors are: > > ../drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or struct member 'blend' not described in 'zynqmp_disp' > ../drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or struct member 'avbuf' not described in 'zynqmp_disp' > ../drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or struct member 'audio' not described in 'zynqmp_disp' > > I don't see the need to document a single-member struct twice. Actually, But if only the struct is documented, then we're documenting the wrong thing. A tool showing to the user what blend.base is would miss that documentation. > maybe it would be better to just lift the .base member to live in > zynqmp_disp. But I think that would be better in another series. Yes, there's not much point with the structs. Tomi
WARNING: multiple messages have this Message-ID (diff)
From: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com> To: Sean Anderson <sean.anderson@linux.dev>, Randy Dunlap <rdunlap@infradead.org> Cc: Michal Simek <michal.simek@amd.com>, David Airlie <airlied@gmail.com>, linux-kernel@vger.kernel.org, Daniel Vetter <daniel@ffwll.ch>, linux-arm-kernel@lists.infradead.org, Laurent Pinchart <laurent.pinchart@ideasonboard.com>, Maarten Lankhorst <maarten.lankhorst@linux.intel.com>, Maxime Ripard <mripard@kernel.org>, Thomas Zimmermann <tzimmermann@suse.de>, dri-devel@lists.freedesktop.org Subject: Re: [PATCH v2 1/8] drm: xlnx: Fix kerneldoc Date: Fri, 22 Mar 2024 07:50:56 +0200 [thread overview] Message-ID: <19d6da67-f9a6-4e01-a956-3b60f0ebf769@ideasonboard.com> (raw) In-Reply-To: <2c38ac1c-cc0e-43b3-86d3-5b6a2f00f9e7@linux.dev> On 21/03/2024 17:33, Sean Anderson wrote: > On 3/20/24 02:05, Randy Dunlap wrote: >> >> >> On 3/19/24 22:42, Tomi Valkeinen wrote: >>> On 20/03/2024 00:51, Sean Anderson wrote: >>>> Fix a few errors in the kerneldoc. Mostly this addresses missing/renamed >>>> members. >>>> >>>> Signed-off-by: Sean Anderson <sean.anderson@linux.dev> >>>> --- >>>> >>>> Changes in v2: >>>> - New >>>> >>>> drivers/gpu/drm/xlnx/zynqmp_disp.c | 6 +++--- >>>> drivers/gpu/drm/xlnx/zynqmp_dpsub.h | 1 + >>>> drivers/gpu/drm/xlnx/zynqmp_kms.h | 4 ++-- >>>> 3 files changed, 6 insertions(+), 5 deletions(-) >>>> >>>> diff --git a/drivers/gpu/drm/xlnx/zynqmp_disp.c b/drivers/gpu/drm/xlnx/zynqmp_disp.c >>>> index 407bc07cec69..f79bf3fb8110 100644 >>>> --- a/drivers/gpu/drm/xlnx/zynqmp_disp.c >>>> +++ b/drivers/gpu/drm/xlnx/zynqmp_disp.c >>>> @@ -128,9 +128,9 @@ struct zynqmp_disp_layer { >>>> * struct zynqmp_disp - Display controller >>>> * @dev: Device structure >>>> * @dpsub: Display subsystem >>>> - * @blend.base: Register I/O base address for the blender >>>> - * @avbuf.base: Register I/O base address for the audio/video buffer manager >>>> - * @audio.base: Registers I/O base address for the audio mixer >>>> + * @blend: Register I/O base address for the blender >>>> + * @avbuf: Register I/O base address for the audio/video buffer manager >>>> + * @audio: Registers I/O base address for the audio mixer >>> >>> Afaics, the kernel doc guide: >>> >>> https://docs.kernel.org/doc-guide/kernel-doc.html#nested-structs-unions >>> >>> says that the current version is correct. Or is the issue that while, say, 'base' is documented, 'blend' was not? >> >> Hi, >> >> I would do it more like so: >> >> --- >> drivers/gpu/drm/xlnx/zynqmp_disp.c | 3 +++ >> 1 file changed, 3 insertions(+) >> >> diff -- a/drivers/gpu/drm/xlnx/zynqmp_disp.c b/drivers/gpu/drm/xlnx/zynqmp_disp.c >> --- a/drivers/gpu/drm/xlnx/zynqmp_disp.c >> +++ b/drivers/gpu/drm/xlnx/zynqmp_disp.c >> @@ -128,8 +128,11 @@ struct zynqmp_disp_layer { >> * struct zynqmp_disp - Display controller >> * @dev: Device structure >> * @dpsub: Display subsystem >> + * @blend: blender iomem info >> * @blend.base: Register I/O base address for the blender >> + * @avbuf: audio/video buffer iomem info >> * @avbuf.base: Register I/O base address for the audio/video buffer manager >> + * @audio: audio mixer iomem info >> * @audio.base: Registers I/O base address for the audio mixer >> * @layers: Layers (planes) >> */ >> >> >> but in my testing, Sean's way or my way result in no warning/errors. >> > > The specific errors are: > > ../drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or struct member 'blend' not described in 'zynqmp_disp' > ../drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or struct member 'avbuf' not described in 'zynqmp_disp' > ../drivers/gpu/drm/xlnx/zynqmp_disp.c:151: warning: Function parameter or struct member 'audio' not described in 'zynqmp_disp' > > I don't see the need to document a single-member struct twice. Actually, But if only the struct is documented, then we're documenting the wrong thing. A tool showing to the user what blend.base is would miss that documentation. > maybe it would be better to just lift the .base member to live in > zynqmp_disp. But I think that would be better in another series. Yes, there's not much point with the structs. Tomi _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
next prev parent reply other threads:[~2024-03-22 5:51 UTC|newest] Thread overview: 72+ messages / expand[flat|nested] mbox.gz Atom feed top 2024-03-19 22:51 [PATCH v2 0/8] drm: zynqmp_dp: Misc. patches and debugfs support Sean Anderson 2024-03-19 22:51 ` Sean Anderson 2024-03-19 22:51 ` [PATCH v2 1/8] drm: xlnx: Fix kerneldoc Sean Anderson 2024-03-19 22:51 ` Sean Anderson 2024-03-20 5:42 ` Tomi Valkeinen 2024-03-20 5:42 ` Tomi Valkeinen 2024-03-20 6:05 ` Randy Dunlap 2024-03-20 6:05 ` Randy Dunlap 2024-03-21 15:33 ` Sean Anderson 2024-03-21 15:33 ` Sean Anderson 2024-03-22 5:50 ` Tomi Valkeinen [this message] 2024-03-22 5:50 ` Tomi Valkeinen 2024-03-22 15:22 ` Sean Anderson 2024-03-22 15:22 ` Sean Anderson 2024-03-19 22:51 ` [PATCH v2 2/8] drm: zynqmp_dp: Downgrade log level for aux retries message Sean Anderson 2024-03-19 22:51 ` Sean Anderson 2024-03-20 5:46 ` Tomi Valkeinen 2024-03-20 5:46 ` Tomi Valkeinen 2024-03-19 22:51 ` [PATCH v2 3/8] drm: zynqmp_dp: Adjust training values per-lane Sean Anderson 2024-03-19 22:51 ` Sean Anderson 2024-03-20 5:57 ` Tomi Valkeinen 2024-03-20 5:57 ` Tomi Valkeinen 2024-03-21 15:35 ` Sean Anderson 2024-03-21 15:35 ` Sean Anderson 2024-03-19 22:51 ` [PATCH v2 4/8] drm: zynqmp_dp: Rearrange zynqmp_dp for better padding Sean Anderson 2024-03-19 22:51 ` Sean Anderson 2024-03-20 6:14 ` Tomi Valkeinen 2024-03-20 6:14 ` Tomi Valkeinen 2024-03-21 15:43 ` Sean Anderson 2024-03-21 15:43 ` Sean Anderson 2024-03-19 22:51 ` [PATCH v2 5/8] drm: zynqmp_dp: Don't retrain the link in our IRQ Sean Anderson 2024-03-19 22:51 ` Sean Anderson 2024-03-20 6:53 ` Tomi Valkeinen 2024-03-20 6:53 ` Tomi Valkeinen 2024-03-21 15:52 ` Sean Anderson 2024-03-21 15:52 ` Sean Anderson 2024-03-21 17:25 ` Tomi Valkeinen 2024-03-21 17:25 ` Tomi Valkeinen 2024-03-21 18:01 ` Sean Anderson 2024-03-21 18:01 ` Sean Anderson 2024-03-21 19:08 ` Tomi Valkeinen 2024-03-21 19:08 ` Tomi Valkeinen 2024-03-21 19:17 ` Sean Anderson 2024-03-21 19:17 ` Sean Anderson 2024-03-22 5:32 ` Tomi Valkeinen 2024-03-22 5:32 ` Tomi Valkeinen 2024-03-22 16:18 ` Sean Anderson 2024-03-22 16:18 ` Sean Anderson 2024-03-22 18:09 ` Tomi Valkeinen 2024-03-22 18:09 ` Tomi Valkeinen 2024-03-22 21:22 ` Sean Anderson 2024-03-22 21:22 ` Sean Anderson 2024-03-23 8:54 ` Tomi Valkeinen 2024-03-23 8:54 ` Tomi Valkeinen 2024-03-19 22:51 ` [PATCH v2 6/8] drm: zynqmp_dp: Add locking Sean Anderson 2024-03-19 22:51 ` Sean Anderson 2024-03-19 22:51 ` [PATCH v2 7/8] drm: zynqmp_dp: Split off several helper functions Sean Anderson 2024-03-19 22:51 ` Sean Anderson 2024-03-20 7:36 ` Tomi Valkeinen 2024-03-20 7:36 ` Tomi Valkeinen 2024-03-19 22:51 ` [PATCH v2 8/8] drm: zynqmp_dp: Add debugfs interface for compliance testing Sean Anderson 2024-03-19 22:51 ` Sean Anderson 2024-03-20 7:49 ` Tomi Valkeinen 2024-03-20 7:49 ` Tomi Valkeinen 2024-03-21 16:08 ` Sean Anderson 2024-03-21 16:08 ` Sean Anderson 2024-03-21 16:31 ` Tomi Valkeinen 2024-03-21 16:31 ` Tomi Valkeinen 2024-03-21 16:35 ` Sean Anderson 2024-03-21 16:35 ` Sean Anderson 2024-03-19 23:02 ` [PATCH v2 0/8] drm: zynqmp_dp: Misc. patches and debugfs support Sean Anderson 2024-03-19 23:02 ` Sean Anderson
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=19d6da67-f9a6-4e01-a956-3b60f0ebf769@ideasonboard.com \ --to=tomi.valkeinen@ideasonboard.com \ --cc=airlied@gmail.com \ --cc=daniel@ffwll.ch \ --cc=dri-devel@lists.freedesktop.org \ --cc=laurent.pinchart@ideasonboard.com \ --cc=linux-arm-kernel@lists.infradead.org \ --cc=linux-kernel@vger.kernel.org \ --cc=maarten.lankhorst@linux.intel.com \ --cc=michal.simek@amd.com \ --cc=mripard@kernel.org \ --cc=rdunlap@infradead.org \ --cc=sean.anderson@linux.dev \ --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: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.