From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 7D406C47DD9 for ; Fri, 22 Mar 2024 15:23:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:In-Reply-To:From:References:Cc:To: Subject:MIME-Version:Date:Message-ID:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=ecrThAsRVOH45HZaOjDPBNhKK8PXrYQw1nJYGyCGhwM=; b=LEBamGpAZGmXPJ fOfnkdkPf94dtsVwxLNuci744q064jS2r8mtQ4Axh1yINVN6HFdFcJ8T8YAnoh2Q9yg2Q4Hstq1U3 zMpoeMLnewuUQeN4DPzss06ShGLAp4DBoRD7cotIX5xW3VJkcoGS6D0l59crpj0S75Il5hpLii14c BN13liT0OCNzYnaHH4JdjmKGoaUN3YC2zD65iaEiqRzCVDj1fzBGNvkEdodxyYeyQW6qPxt84lqLS FPBiqomtwvu6ntYTn2LHX+T4pnr3KptvKiDhSn275pGA3LpsSMT9nUUvZYRy6yMIoYDTLPa3f0fOX FVYDgWnkXvenTImbiPFQ==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.97.1 #2 (Red Hat Linux)) id 1rngjb-00000007jsW-2C9Y; Fri, 22 Mar 2024 15:23:07 +0000 Received: from out-177.mta0.migadu.com ([2001:41d0:1004:224b::b1]) by bombadil.infradead.org with esmtps (Exim 4.97.1 #2 (Red Hat Linux)) id 1rngjX-00000007jpw-3zgd for linux-arm-kernel@lists.infradead.org; Fri, 22 Mar 2024 15:23:06 +0000 Message-ID: <9063f7cd-e922-484f-a2ac-cf84c4f47100@linux.dev> DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.dev; s=key1; t=1711120976; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=n14/GAey1MVQQZ9496BWTZLRI/CaUeVuyvNjQAWmb5w=; b=xvYY0svqy/qpIv8OVXzIJyTXGPfIQ8a+wpEAnw9O+QTGZHAcRZMZBQVKKx6XXX7TSoVUlC GnkjohFYMbvlftzsyBSuC9aWBUWd2vLYgSf5Cx+aALEGQiIaIG338DTeE20B5GvyViTxIy r3J597Jj4gHupcJDt3bMrHISFxO9h/4= Date: Fri, 22 Mar 2024 11:22:52 -0400 MIME-Version: 1.0 Subject: Re: [PATCH v2 1/8] drm: xlnx: Fix kerneldoc Content-Language: en-US To: Tomi Valkeinen , Randy Dunlap Cc: Michal Simek , David Airlie , linux-kernel@vger.kernel.org, Daniel Vetter , linux-arm-kernel@lists.infradead.org, Laurent Pinchart , Maarten Lankhorst , Maxime Ripard , Thomas Zimmermann , dri-devel@lists.freedesktop.org References: <20240319225122.3048400-1-sean.anderson@linux.dev> <20240319225122.3048400-2-sean.anderson@linux.dev> <2c38ac1c-cc0e-43b3-86d3-5b6a2f00f9e7@linux.dev> <19d6da67-f9a6-4e01-a956-3b60f0ebf769@ideasonboard.com> X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. From: Sean Anderson In-Reply-To: <19d6da67-f9a6-4e01-a956-3b60f0ebf769@ideasonboard.com> X-Migadu-Flow: FLOW_OUT X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20240322_082304_295566_6298F78A X-CRM114-Status: GOOD ( 20.94 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org On 3/22/24 01:50, Tomi Valkeinen wrote: > 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 >>>>> --- >>>>> >>>>> 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. Are there any such tools? kerneldoc e.g. just prints the definition and then a list of members with documentation. So from the user's perspective the only thing which changes is the name. --Sean >> 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