From mboxrd@z Thu Jan 1 00:00:00 1970 From: Lee Jones Date: Fri, 26 Jun 2020 15:33:51 +0000 Subject: Re: [PATCH 3/8] backlight: ili922x: Add missing kerneldoc descriptions for CHECK_FREQ_REG() args Message-Id: <20200626153351.GD177734@dell> List-Id: References: <20200624145721.2590327-1-lee.jones@linaro.org> <20200624145721.2590327-4-lee.jones@linaro.org> <20200625094051.u4hanl3rycczlwiy@holly.lan> <20200625103334.GO954398@dell> <20200626095405.nzhqsfjegj6qg2ro@holly.lan> In-Reply-To: <20200626095405.nzhqsfjegj6qg2ro@holly.lan> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 8bit To: Daniel Thompson Cc: linux-fbdev@vger.kernel.org, Bartlomiej Zolnierkiewicz , jingoohan1@gmail.com, linux-kernel@vger.kernel.org, stable@vger.kernel.org, dri-devel@lists.freedesktop.org, Software Engineering , linux-arm-kernel@lists.infradead.org On Fri, 26 Jun 2020, Daniel Thompson wrote: > On Thu, Jun 25, 2020 at 11:33:34AM +0100, Lee Jones wrote: > > On Thu, 25 Jun 2020, Daniel Thompson wrote: > > > > > On Wed, Jun 24, 2020 at 03:57:16PM +0100, Lee Jones wrote: > > > > Kerneldoc syntax is used, but not complete. Descriptions required. > > > > > > > > Prevents warnings like: > > > > > > > > drivers/video/backlight/ili922x.c:116: warning: Function parameter or member 's' not described in 'CHECK_FREQ_REG' > > > > drivers/video/backlight/ili922x.c:116: warning: Function parameter or member 'x' not described in 'CHECK_FREQ_REG' > > > > > > > > Cc: > > > > Cc: Bartlomiej Zolnierkiewicz > > > > Cc: Software Engineering > > > > Signed-off-by: Lee Jones > > > > --- > > > > drivers/video/backlight/ili922x.c | 2 ++ > > > > 1 file changed, 2 insertions(+) > > > > > > > > diff --git a/drivers/video/backlight/ili922x.c b/drivers/video/backlight/ili922x.c > > > > index 9c5aa3fbb2842..8cb4b9d3c3bba 100644 > > > > --- a/drivers/video/backlight/ili922x.c > > > > +++ b/drivers/video/backlight/ili922x.c > > > > @@ -107,6 +107,8 @@ > > > > * lower frequency when the registers are read/written. > > > > * The macro sets the frequency in the spi_transfer structure if > > > > * the frequency exceeds the maximum value. > > > > + * @s: pointer to controller side proxy for an SPI slave device > > > > > > What's wrong with "a pointer to an SPI device"? > > > > > > I am aware, having looked it up to find out what the above actually > > > means, that this is how struct spi_device is described in its own kernel > > > doc but quoting at that level of detail of both overkill and confusing. > > > > I figured that using the official description would be better than > > making something up. However if you think it's better to KISS, then I > > can change it. > > Yes, I'd strongly prefer KISS here. > > I know it is an "I am the world" argument[1] but I found using such a > dogmatically accurate description out of context to be very confusing > and therefore I don't think such a comment improves readability. > > [1]: See #3 from http://www.leany.com/logic/Adams.html It's fine, you are the world, I get it. ;) Do you even like Country music? Will fix! -- Lee Jones [李琼斯] Senior Technical Lead - Developer Services Linaro.org │ Open source software for Arm SoCs Follow Linaro: Facebook | Twitter | Blog 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 X-Spam-Level: X-Spam-Status: No, score=-7.0 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 51866C433DF for ; Fri, 26 Jun 2020 15:36:04 +0000 (UTC) Received: from merlin.infradead.org (merlin.infradead.org [205.233.59.134]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 22C1A20706 for ; Fri, 26 Jun 2020 15:36:04 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="MlXhTcmI"; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="Im1TNyjY" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 22C1A20706 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=merlin.20170209; h=Sender:Content-Transfer-Encoding: Content-Type:Cc:List-Subscribe:List-Help:List-Post:List-Archive: List-Unsubscribe:List-Id:In-Reply-To:MIME-Version:References:Message-ID: Subject:To:From:Date:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=RqPn9oS9TEgIgFCcYaHI2wjOT52koA4F8GZ0BICXbsE=; b=MlXhTcmIi0Vi2SSlqJ2vSlvB9 BsQTAIFKPUx7TXZtElIXVwA7byx7Zw5pL8Erd+1m5R+hrBgLTCVWfKAJyW8YEByzHREH3fkW3RSXn FDeneflN3DdU9aB775KCLXnrRyXbYks9VIB+IsPKBxK3kdzee1MtbB7tHnjcw80yu+94aywHTTKHF wIfPklVFZz9+0rmC0YFy7IhW12r6TDP/7FRft+DIk6dqzurQkelGQz6TLVC49rfQWxp8NatQhnXzS G31ttuFryrcUKkzJcBlf2twNcmjfZfexp2LYbHY1q6zDHHrZDiSnNE2aryNfAE7HBRJiUBUw58FUo hVX/paQFQ==; Received: from localhost ([::1] helo=merlin.infradead.org) by merlin.infradead.org with esmtp (Exim 4.92.3 #3 (Red Hat Linux)) id 1joqMX-0008VB-CG; Fri, 26 Jun 2020 15:33:59 +0000 Received: from mail-wm1-x342.google.com ([2a00:1450:4864:20::342]) by merlin.infradead.org with esmtps (Exim 4.92.3 #3 (Red Hat Linux)) id 1joqMU-0008UM-Dz for linux-arm-kernel@lists.infradead.org; Fri, 26 Jun 2020 15:33:55 +0000 Received: by mail-wm1-x342.google.com with SMTP id o8so9213380wmh.4 for ; Fri, 26 Jun 2020 08:33:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:content-transfer-encoding:in-reply-to; bh=rpso9ySNKoLDGZyCP/hQvs97M6SXDiiUl7b7MavvpwM=; b=Im1TNyjYUqGtSxb3sVpOQyDfuWo+4jL/eqZNHs4NDDTYEFyid04tQdyu89ASBScZ4r wb24XBrOxce/WjPuyNXPXoUHQtfJiOu0kaAMJjR3M59cyn6Vkqe368y2feEo+qQEiBk1 DGBfapEIfDFuUQ2BVVIu2qVIvQnFFinKhlLC/DFjzG2Vl42KM9ir4BThZQhjbOqbEaLn PIGe/3KXrsysRdikgnP8sEL3JiLrgrISIBIssg0wXfm9CiCOt594i2d+P+H+yy96DPWd chrGgttiyWu7uhIOKgZbaVf2bTgCFyCeXiE4mMc/P5bBOpgpq8XeNZk2VCtLj5y9RojH FdvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:content-transfer-encoding :in-reply-to; bh=rpso9ySNKoLDGZyCP/hQvs97M6SXDiiUl7b7MavvpwM=; b=Thexm0TzzJ51HVJldGQAZpKR9v0beCCNOsdtm0woBWH2Ajj51q8e2mlAs9v74BmlXb U8ujwt05QgGQ0Hb+ohUYbg4FNEdq9mBtofN1IMWRwBTt/zeXY30lbpRHYoZ5+YDs16BY qcWhrjc3N06fS/zBU/a5+sFRcPIxZQDH9rTcVNBi/yhRo08L73UnHoI5EnZqEnuwM1AG o6xG+M5o5kJ6jdP0Ycagqjs3cfpAjR5gAYSebU1AANHNGr23Ktj4hcf5OB2W2/ewCeam NX7VmNnauAP9nFK4Apie9pTcH9czr8US1jaGjKpIvJrlwI0Q99Aacd9ldSN6C67esLtq 7J/A== X-Gm-Message-State: AOAM530d3D/n0pKQuPtp1Fv9NOIEGqT4Ng9+U8UqDiaJoChcvZGdG1w4 Am5QNy03mH+LzhfE74cbGuYGRQ== X-Google-Smtp-Source: ABdhPJz9yrxY45T9SAy1cdsmEGjRTcOB+Cz9/AF+lu25KlsF3R66G6fdX+qT3KF8kVohKRgE/ySkTg== X-Received: by 2002:a1c:32c4:: with SMTP id y187mr4112202wmy.79.1593185633299; Fri, 26 Jun 2020 08:33:53 -0700 (PDT) Received: from dell ([2.27.35.144]) by smtp.gmail.com with ESMTPSA id f16sm18168315wmh.27.2020.06.26.08.33.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 26 Jun 2020 08:33:52 -0700 (PDT) Date: Fri, 26 Jun 2020 16:33:51 +0100 From: Lee Jones To: Daniel Thompson Subject: Re: [PATCH 3/8] backlight: ili922x: Add missing kerneldoc descriptions for CHECK_FREQ_REG() args Message-ID: <20200626153351.GD177734@dell> References: <20200624145721.2590327-1-lee.jones@linaro.org> <20200624145721.2590327-4-lee.jones@linaro.org> <20200625094051.u4hanl3rycczlwiy@holly.lan> <20200625103334.GO954398@dell> <20200626095405.nzhqsfjegj6qg2ro@holly.lan> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20200626095405.nzhqsfjegj6qg2ro@holly.lan> X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: linux-fbdev@vger.kernel.org, Bartlomiej Zolnierkiewicz , jingoohan1@gmail.com, linux-kernel@vger.kernel.org, stable@vger.kernel.org, dri-devel@lists.freedesktop.org, Software Engineering , linux-arm-kernel@lists.infradead.org Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org T24gRnJpLCAyNiBKdW4gMjAyMCwgRGFuaWVsIFRob21wc29uIHdyb3RlOgoKPiBPbiBUaHUsIEp1 biAyNSwgMjAyMCBhdCAxMTozMzozNEFNICswMTAwLCBMZWUgSm9uZXMgd3JvdGU6Cj4gPiBPbiBU aHUsIDI1IEp1biAyMDIwLCBEYW5pZWwgVGhvbXBzb24gd3JvdGU6Cj4gPiAKPiA+ID4gT24gV2Vk LCBKdW4gMjQsIDIwMjAgYXQgMDM6NTc6MTZQTSArMDEwMCwgTGVlIEpvbmVzIHdyb3RlOgo+ID4g PiA+IEtlcm5lbGRvYyBzeW50YXggaXMgdXNlZCwgYnV0IG5vdCBjb21wbGV0ZS4gIERlc2NyaXB0 aW9ucyByZXF1aXJlZC4KPiA+ID4gPiAKPiA+ID4gPiBQcmV2ZW50cyB3YXJuaW5ncyBsaWtlOgo+ ID4gPiA+IAo+ID4gPiA+ICBkcml2ZXJzL3ZpZGVvL2JhY2tsaWdodC9pbGk5MjJ4LmM6MTE2OiB3 YXJuaW5nOiBGdW5jdGlvbiBwYXJhbWV0ZXIgb3IgbWVtYmVyICdzJyBub3QgZGVzY3JpYmVkIGlu ICdDSEVDS19GUkVRX1JFRycKPiA+ID4gPiAgZHJpdmVycy92aWRlby9iYWNrbGlnaHQvaWxpOTIy eC5jOjExNjogd2FybmluZzogRnVuY3Rpb24gcGFyYW1ldGVyIG9yIG1lbWJlciAneCcgbm90IGRl c2NyaWJlZCBpbiAnQ0hFQ0tfRlJFUV9SRUcnCj4gPiA+ID4gCj4gPiA+ID4gQ2M6IDxzdGFibGVA dmdlci5rZXJuZWwub3JnPgo+ID4gPiA+IENjOiBCYXJ0bG9taWVqIFpvbG5pZXJraWV3aWN6IDxi LnpvbG5pZXJraWVAc2Ftc3VuZy5jb20+Cj4gPiA+ID4gQ2M6IFNvZnR3YXJlIEVuZ2luZWVyaW5n IDxzYmFiaWNAZGVueC5kZT4KPiA+ID4gPiBTaWduZWQtb2ZmLWJ5OiBMZWUgSm9uZXMgPGxlZS5q b25lc0BsaW5hcm8ub3JnPgo+ID4gPiA+IC0tLQo+ID4gPiA+ICBkcml2ZXJzL3ZpZGVvL2JhY2ts aWdodC9pbGk5MjJ4LmMgfCAyICsrCj4gPiA+ID4gIDEgZmlsZSBjaGFuZ2VkLCAyIGluc2VydGlv bnMoKykKPiA+ID4gPiAKPiA+ID4gPiBkaWZmIC0tZ2l0IGEvZHJpdmVycy92aWRlby9iYWNrbGln aHQvaWxpOTIyeC5jIGIvZHJpdmVycy92aWRlby9iYWNrbGlnaHQvaWxpOTIyeC5jCj4gPiA+ID4g aW5kZXggOWM1YWEzZmJiMjg0Mi4uOGNiNGI5ZDNjM2JiYSAxMDA2NDQKPiA+ID4gPiAtLS0gYS9k cml2ZXJzL3ZpZGVvL2JhY2tsaWdodC9pbGk5MjJ4LmMKPiA+ID4gPiArKysgYi9kcml2ZXJzL3Zp ZGVvL2JhY2tsaWdodC9pbGk5MjJ4LmMKPiA+ID4gPiBAQCAtMTA3LDYgKzEwNyw4IEBACj4gPiA+ ID4gICAqCWxvd2VyIGZyZXF1ZW5jeSB3aGVuIHRoZSByZWdpc3RlcnMgYXJlIHJlYWQvd3JpdHRl bi4KPiA+ID4gPiAgICoJVGhlIG1hY3JvIHNldHMgdGhlIGZyZXF1ZW5jeSBpbiB0aGUgc3BpX3Ry YW5zZmVyIHN0cnVjdHVyZSBpZgo+ID4gPiA+ICAgKgl0aGUgZnJlcXVlbmN5IGV4Y2VlZHMgdGhl IG1heGltdW0gdmFsdWUuCj4gPiA+ID4gKyAqIEBzOiBwb2ludGVyIHRvIGNvbnRyb2xsZXIgc2lk ZSBwcm94eSBmb3IgYW4gU1BJIHNsYXZlIGRldmljZQo+ID4gPiAKPiA+ID4gV2hhdCdzIHdyb25n IHdpdGggImEgcG9pbnRlciB0byBhbiBTUEkgZGV2aWNlIj8KPiA+ID4gCj4gPiA+IEkgYW0gYXdh cmUsIGhhdmluZyBsb29rZWQgaXQgdXAgdG8gZmluZCBvdXQgd2hhdCB0aGUgYWJvdmUgYWN0dWFs bHkKPiA+ID4gbWVhbnMsIHRoYXQgdGhpcyBpcyBob3cgc3RydWN0IHNwaV9kZXZpY2UgaXMgZGVz Y3JpYmVkIGluIGl0cyBvd24ga2VybmVsCj4gPiA+IGRvYyBidXQgcXVvdGluZyBhdCB0aGF0IGxl dmVsIG9mIGRldGFpbCBvZiBib3RoIG92ZXJraWxsIGFuZCBjb25mdXNpbmcuCj4gPiAKPiA+IEkg ZmlndXJlZCB0aGF0IHVzaW5nIHRoZSBvZmZpY2lhbCBkZXNjcmlwdGlvbiB3b3VsZCBiZSBiZXR0 ZXIgdGhhbgo+ID4gbWFraW5nIHNvbWV0aGluZyB1cC4gIEhvd2V2ZXIgaWYgeW91IHRoaW5rIGl0 J3MgYmV0dGVyIHRvIEtJU1MsIHRoZW4gSQo+ID4gY2FuIGNoYW5nZSBpdC4KPiAKPiBZZXMsIEkn ZCBzdHJvbmdseSBwcmVmZXIgS0lTUyBoZXJlLgo+IAo+IEkga25vdyBpdCBpcyBhbiAiSSBhbSB0 aGUgd29ybGQiIGFyZ3VtZW50WzFdIGJ1dCBJIGZvdW5kIHVzaW5nIHN1Y2ggYQo+IGRvZ21hdGlj YWxseSBhY2N1cmF0ZSBkZXNjcmlwdGlvbiBvdXQgb2YgY29udGV4dCB0byBiZSB2ZXJ5IGNvbmZ1 c2luZwo+IGFuZCB0aGVyZWZvcmUgSSBkb24ndCB0aGluayBzdWNoIGEgY29tbWVudCBpbXByb3Zl cyByZWFkYWJpbGl0eS4KPiAKPiBbMV06IFNlZSAjMyBmcm9tIGh0dHA6Ly93d3cubGVhbnkuY29t L2xvZ2ljL0FkYW1zLmh0bWwKCkl0J3MgZmluZSwgeW91IGFyZSB0aGUgd29ybGQsIEkgZ2V0IGl0 LiA7KQoKRG8geW91IGV2ZW4gbGlrZSBDb3VudHJ5IG11c2ljPwoKV2lsbCBmaXghCgotLSAKTGVl IEpvbmVzIFvmnY7nkLzmlq9dClNlbmlvciBUZWNobmljYWwgTGVhZCAtIERldmVsb3BlciBTZXJ2 aWNlcwpMaW5hcm8ub3JnIOKUgiBPcGVuIHNvdXJjZSBzb2Z0d2FyZSBmb3IgQXJtIFNvQ3MKRm9s bG93IExpbmFybzogRmFjZWJvb2sgfCBUd2l0dGVyIHwgQmxvZwoKX19fX19fX19fX19fX19fX19f X19fX19fX19fX19fX19fX19fX19fX19fX19fX18KbGludXgtYXJtLWtlcm5lbCBtYWlsaW5nIGxp c3QKbGludXgtYXJtLWtlcm5lbEBsaXN0cy5pbmZyYWRlYWQub3JnCmh0dHA6Ly9saXN0cy5pbmZy YWRlYWQub3JnL21haWxtYW4vbGlzdGluZm8vbGludXgtYXJtLWtlcm5lbAo= 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 X-Spam-Level: X-Spam-Status: No, score=-6.8 required=3.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 65A71C433DF for ; Fri, 26 Jun 2020 15:33:56 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 397822080C for ; Fri, 26 Jun 2020 15:33:56 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="Im1TNyjY" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 397822080C Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=dri-devel-bounces@lists.freedesktop.org Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id A8A6B6ECBD; Fri, 26 Jun 2020 15:33:55 +0000 (UTC) Received: from mail-wm1-x342.google.com (mail-wm1-x342.google.com [IPv6:2a00:1450:4864:20::342]) by gabe.freedesktop.org (Postfix) with ESMTPS id B4CB46ECBD for ; Fri, 26 Jun 2020 15:33:54 +0000 (UTC) Received: by mail-wm1-x342.google.com with SMTP id o8so9213381wmh.4 for ; Fri, 26 Jun 2020 08:33:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:content-transfer-encoding:in-reply-to; bh=rpso9ySNKoLDGZyCP/hQvs97M6SXDiiUl7b7MavvpwM=; b=Im1TNyjYUqGtSxb3sVpOQyDfuWo+4jL/eqZNHs4NDDTYEFyid04tQdyu89ASBScZ4r wb24XBrOxce/WjPuyNXPXoUHQtfJiOu0kaAMJjR3M59cyn6Vkqe368y2feEo+qQEiBk1 DGBfapEIfDFuUQ2BVVIu2qVIvQnFFinKhlLC/DFjzG2Vl42KM9ir4BThZQhjbOqbEaLn PIGe/3KXrsysRdikgnP8sEL3JiLrgrISIBIssg0wXfm9CiCOt594i2d+P+H+yy96DPWd chrGgttiyWu7uhIOKgZbaVf2bTgCFyCeXiE4mMc/P5bBOpgpq8XeNZk2VCtLj5y9RojH FdvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:content-transfer-encoding :in-reply-to; bh=rpso9ySNKoLDGZyCP/hQvs97M6SXDiiUl7b7MavvpwM=; b=NhcACNJQvKW4lXVT5RA50dN5mOai1GUOZ9VUzfwuWD8NxRB09zph02xYh0k0iUVEcg oXK+MpalkiD3PUm5tEdlJy9MH/TSpIXo/y4QFrsJjMF1omhZjcXxRpvFJEGS83cl4sGx w5vXdZW1v3x8swYDLA9W4AV7OXAyIyeipOnGH00sK+9pAhddfyqOhfthEfCUBrli7n79 WwBYRwjyLhYtmVskhnl0tceXFD6tyR+gnnG7vNBO0xzYga7k4XFB+w2ORip1kUkHbcA4 Zb5T0WnGI94sExJnYXKtMZ4kofDB10+RRqHROiHhYrq+r61SfbDOAa2kL7r7yNywFd8b SszA== X-Gm-Message-State: AOAM530WU3ng/FK4Eq6BZzEwhnZUfHo/WUDpAO0Lj5Vut5RErxUMbnwG yfltakje67vy3RC6XJtxiMOZcQ== X-Google-Smtp-Source: ABdhPJz9yrxY45T9SAy1cdsmEGjRTcOB+Cz9/AF+lu25KlsF3R66G6fdX+qT3KF8kVohKRgE/ySkTg== X-Received: by 2002:a1c:32c4:: with SMTP id y187mr4112202wmy.79.1593185633299; Fri, 26 Jun 2020 08:33:53 -0700 (PDT) Received: from dell ([2.27.35.144]) by smtp.gmail.com with ESMTPSA id f16sm18168315wmh.27.2020.06.26.08.33.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 26 Jun 2020 08:33:52 -0700 (PDT) Date: Fri, 26 Jun 2020 16:33:51 +0100 From: Lee Jones To: Daniel Thompson Subject: Re: [PATCH 3/8] backlight: ili922x: Add missing kerneldoc descriptions for CHECK_FREQ_REG() args Message-ID: <20200626153351.GD177734@dell> References: <20200624145721.2590327-1-lee.jones@linaro.org> <20200624145721.2590327-4-lee.jones@linaro.org> <20200625094051.u4hanl3rycczlwiy@holly.lan> <20200625103334.GO954398@dell> <20200626095405.nzhqsfjegj6qg2ro@holly.lan> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20200626095405.nzhqsfjegj6qg2ro@holly.lan> X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: linux-fbdev@vger.kernel.org, Bartlomiej Zolnierkiewicz , jingoohan1@gmail.com, linux-kernel@vger.kernel.org, stable@vger.kernel.org, dri-devel@lists.freedesktop.org, Software Engineering , linux-arm-kernel@lists.infradead.org Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" T24gRnJpLCAyNiBKdW4gMjAyMCwgRGFuaWVsIFRob21wc29uIHdyb3RlOgoKPiBPbiBUaHUsIEp1 biAyNSwgMjAyMCBhdCAxMTozMzozNEFNICswMTAwLCBMZWUgSm9uZXMgd3JvdGU6Cj4gPiBPbiBU aHUsIDI1IEp1biAyMDIwLCBEYW5pZWwgVGhvbXBzb24gd3JvdGU6Cj4gPiAKPiA+ID4gT24gV2Vk LCBKdW4gMjQsIDIwMjAgYXQgMDM6NTc6MTZQTSArMDEwMCwgTGVlIEpvbmVzIHdyb3RlOgo+ID4g PiA+IEtlcm5lbGRvYyBzeW50YXggaXMgdXNlZCwgYnV0IG5vdCBjb21wbGV0ZS4gIERlc2NyaXB0 aW9ucyByZXF1aXJlZC4KPiA+ID4gPiAKPiA+ID4gPiBQcmV2ZW50cyB3YXJuaW5ncyBsaWtlOgo+ ID4gPiA+IAo+ID4gPiA+ICBkcml2ZXJzL3ZpZGVvL2JhY2tsaWdodC9pbGk5MjJ4LmM6MTE2OiB3 YXJuaW5nOiBGdW5jdGlvbiBwYXJhbWV0ZXIgb3IgbWVtYmVyICdzJyBub3QgZGVzY3JpYmVkIGlu ICdDSEVDS19GUkVRX1JFRycKPiA+ID4gPiAgZHJpdmVycy92aWRlby9iYWNrbGlnaHQvaWxpOTIy eC5jOjExNjogd2FybmluZzogRnVuY3Rpb24gcGFyYW1ldGVyIG9yIG1lbWJlciAneCcgbm90IGRl c2NyaWJlZCBpbiAnQ0hFQ0tfRlJFUV9SRUcnCj4gPiA+ID4gCj4gPiA+ID4gQ2M6IDxzdGFibGVA dmdlci5rZXJuZWwub3JnPgo+ID4gPiA+IENjOiBCYXJ0bG9taWVqIFpvbG5pZXJraWV3aWN6IDxi LnpvbG5pZXJraWVAc2Ftc3VuZy5jb20+Cj4gPiA+ID4gQ2M6IFNvZnR3YXJlIEVuZ2luZWVyaW5n IDxzYmFiaWNAZGVueC5kZT4KPiA+ID4gPiBTaWduZWQtb2ZmLWJ5OiBMZWUgSm9uZXMgPGxlZS5q b25lc0BsaW5hcm8ub3JnPgo+ID4gPiA+IC0tLQo+ID4gPiA+ICBkcml2ZXJzL3ZpZGVvL2JhY2ts aWdodC9pbGk5MjJ4LmMgfCAyICsrCj4gPiA+ID4gIDEgZmlsZSBjaGFuZ2VkLCAyIGluc2VydGlv bnMoKykKPiA+ID4gPiAKPiA+ID4gPiBkaWZmIC0tZ2l0IGEvZHJpdmVycy92aWRlby9iYWNrbGln aHQvaWxpOTIyeC5jIGIvZHJpdmVycy92aWRlby9iYWNrbGlnaHQvaWxpOTIyeC5jCj4gPiA+ID4g aW5kZXggOWM1YWEzZmJiMjg0Mi4uOGNiNGI5ZDNjM2JiYSAxMDA2NDQKPiA+ID4gPiAtLS0gYS9k cml2ZXJzL3ZpZGVvL2JhY2tsaWdodC9pbGk5MjJ4LmMKPiA+ID4gPiArKysgYi9kcml2ZXJzL3Zp ZGVvL2JhY2tsaWdodC9pbGk5MjJ4LmMKPiA+ID4gPiBAQCAtMTA3LDYgKzEwNyw4IEBACj4gPiA+ ID4gICAqCWxvd2VyIGZyZXF1ZW5jeSB3aGVuIHRoZSByZWdpc3RlcnMgYXJlIHJlYWQvd3JpdHRl bi4KPiA+ID4gPiAgICoJVGhlIG1hY3JvIHNldHMgdGhlIGZyZXF1ZW5jeSBpbiB0aGUgc3BpX3Ry YW5zZmVyIHN0cnVjdHVyZSBpZgo+ID4gPiA+ICAgKgl0aGUgZnJlcXVlbmN5IGV4Y2VlZHMgdGhl IG1heGltdW0gdmFsdWUuCj4gPiA+ID4gKyAqIEBzOiBwb2ludGVyIHRvIGNvbnRyb2xsZXIgc2lk ZSBwcm94eSBmb3IgYW4gU1BJIHNsYXZlIGRldmljZQo+ID4gPiAKPiA+ID4gV2hhdCdzIHdyb25n IHdpdGggImEgcG9pbnRlciB0byBhbiBTUEkgZGV2aWNlIj8KPiA+ID4gCj4gPiA+IEkgYW0gYXdh cmUsIGhhdmluZyBsb29rZWQgaXQgdXAgdG8gZmluZCBvdXQgd2hhdCB0aGUgYWJvdmUgYWN0dWFs bHkKPiA+ID4gbWVhbnMsIHRoYXQgdGhpcyBpcyBob3cgc3RydWN0IHNwaV9kZXZpY2UgaXMgZGVz Y3JpYmVkIGluIGl0cyBvd24ga2VybmVsCj4gPiA+IGRvYyBidXQgcXVvdGluZyBhdCB0aGF0IGxl dmVsIG9mIGRldGFpbCBvZiBib3RoIG92ZXJraWxsIGFuZCBjb25mdXNpbmcuCj4gPiAKPiA+IEkg ZmlndXJlZCB0aGF0IHVzaW5nIHRoZSBvZmZpY2lhbCBkZXNjcmlwdGlvbiB3b3VsZCBiZSBiZXR0 ZXIgdGhhbgo+ID4gbWFraW5nIHNvbWV0aGluZyB1cC4gIEhvd2V2ZXIgaWYgeW91IHRoaW5rIGl0 J3MgYmV0dGVyIHRvIEtJU1MsIHRoZW4gSQo+ID4gY2FuIGNoYW5nZSBpdC4KPiAKPiBZZXMsIEkn ZCBzdHJvbmdseSBwcmVmZXIgS0lTUyBoZXJlLgo+IAo+IEkga25vdyBpdCBpcyBhbiAiSSBhbSB0 aGUgd29ybGQiIGFyZ3VtZW50WzFdIGJ1dCBJIGZvdW5kIHVzaW5nIHN1Y2ggYQo+IGRvZ21hdGlj YWxseSBhY2N1cmF0ZSBkZXNjcmlwdGlvbiBvdXQgb2YgY29udGV4dCB0byBiZSB2ZXJ5IGNvbmZ1 c2luZwo+IGFuZCB0aGVyZWZvcmUgSSBkb24ndCB0aGluayBzdWNoIGEgY29tbWVudCBpbXByb3Zl cyByZWFkYWJpbGl0eS4KPiAKPiBbMV06IFNlZSAjMyBmcm9tIGh0dHA6Ly93d3cubGVhbnkuY29t L2xvZ2ljL0FkYW1zLmh0bWwKCkl0J3MgZmluZSwgeW91IGFyZSB0aGUgd29ybGQsIEkgZ2V0IGl0 LiA7KQoKRG8geW91IGV2ZW4gbGlrZSBDb3VudHJ5IG11c2ljPwoKV2lsbCBmaXghCgotLSAKTGVl IEpvbmVzIFvmnY7nkLzmlq9dClNlbmlvciBUZWNobmljYWwgTGVhZCAtIERldmVsb3BlciBTZXJ2 aWNlcwpMaW5hcm8ub3JnIOKUgiBPcGVuIHNvdXJjZSBzb2Z0d2FyZSBmb3IgQXJtIFNvQ3MKRm9s bG93IExpbmFybzogRmFjZWJvb2sgfCBUd2l0dGVyIHwgQmxvZwpfX19fX19fX19fX19fX19fX19f X19fX19fX19fX19fX19fX19fX19fX19fX19fXwpkcmktZGV2ZWwgbWFpbGluZyBsaXN0CmRyaS1k ZXZlbEBsaXN0cy5mcmVlZGVza3RvcC5vcmcKaHR0cHM6Ly9saXN0cy5mcmVlZGVza3RvcC5vcmcv bWFpbG1hbi9saXN0aW5mby9kcmktZGV2ZWwK 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 X-Spam-Level: X-Spam-Status: No, score=-7.1 required=3.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id F2F90C433E1 for ; Fri, 26 Jun 2020 15:33:56 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id D0EC820E65 for ; Fri, 26 Jun 2020 15:33:56 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="Im1TNyjY" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728742AbgFZPdz (ORCPT ); Fri, 26 Jun 2020 11:33:55 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53250 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726870AbgFZPdy (ORCPT ); Fri, 26 Jun 2020 11:33:54 -0400 Received: from mail-wm1-x343.google.com (mail-wm1-x343.google.com [IPv6:2a00:1450:4864:20::343]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9CE0AC03E97A for ; Fri, 26 Jun 2020 08:33:54 -0700 (PDT) Received: by mail-wm1-x343.google.com with SMTP id q15so9217982wmj.2 for ; Fri, 26 Jun 2020 08:33:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:content-transfer-encoding:in-reply-to; bh=rpso9ySNKoLDGZyCP/hQvs97M6SXDiiUl7b7MavvpwM=; b=Im1TNyjYUqGtSxb3sVpOQyDfuWo+4jL/eqZNHs4NDDTYEFyid04tQdyu89ASBScZ4r wb24XBrOxce/WjPuyNXPXoUHQtfJiOu0kaAMJjR3M59cyn6Vkqe368y2feEo+qQEiBk1 DGBfapEIfDFuUQ2BVVIu2qVIvQnFFinKhlLC/DFjzG2Vl42KM9ir4BThZQhjbOqbEaLn PIGe/3KXrsysRdikgnP8sEL3JiLrgrISIBIssg0wXfm9CiCOt594i2d+P+H+yy96DPWd chrGgttiyWu7uhIOKgZbaVf2bTgCFyCeXiE4mMc/P5bBOpgpq8XeNZk2VCtLj5y9RojH FdvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:content-transfer-encoding :in-reply-to; bh=rpso9ySNKoLDGZyCP/hQvs97M6SXDiiUl7b7MavvpwM=; b=JLX74GcKCdepLrDEnDQPAA/kGmLt9JH1CJ+FoduRL89tv8ZVBqzBcGd1UUNWFZjcMS wnS11q+hYGiMqROec9lvMtqV05KkMoQdf7wEGFCP0awBxG1N13ueC6wbUc0AAytS2o/P GvKJkmyPc2LJv2ZCFC5y+YQkMcoQ1sydMhbFa0FPfPIBqo/bD1esFZd2P00cGK1u9HpJ Dh+PFx8/Numc2XpvqzzUybyGd//39MNnH6zLmzvsCZ75q4hua5VuXOlrfuMMNW/0zzCV wO9GqO+aHAVdotEVdvA4KChFkBgxpF9/yiiHjvJLzCqpwLAzaIco+W0bejJ/JqFMtnvP WtEA== X-Gm-Message-State: AOAM532ITjwdaCT5mK9FvTMv+4OkxQg6BQ9eMPxTVRBFY6xdRm067cpp debksE0cVMpcenzONkZ5rvKY8w== X-Google-Smtp-Source: ABdhPJz9yrxY45T9SAy1cdsmEGjRTcOB+Cz9/AF+lu25KlsF3R66G6fdX+qT3KF8kVohKRgE/ySkTg== X-Received: by 2002:a1c:32c4:: with SMTP id y187mr4112202wmy.79.1593185633299; Fri, 26 Jun 2020 08:33:53 -0700 (PDT) Received: from dell ([2.27.35.144]) by smtp.gmail.com with ESMTPSA id f16sm18168315wmh.27.2020.06.26.08.33.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 26 Jun 2020 08:33:52 -0700 (PDT) Date: Fri, 26 Jun 2020 16:33:51 +0100 From: Lee Jones To: Daniel Thompson Cc: jingoohan1@gmail.com, dri-devel@lists.freedesktop.org, linux-fbdev@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-kernel@vger.kernel.org, stable@vger.kernel.org, Bartlomiej Zolnierkiewicz , Software Engineering Subject: Re: [PATCH 3/8] backlight: ili922x: Add missing kerneldoc descriptions for CHECK_FREQ_REG() args Message-ID: <20200626153351.GD177734@dell> References: <20200624145721.2590327-1-lee.jones@linaro.org> <20200624145721.2590327-4-lee.jones@linaro.org> <20200625094051.u4hanl3rycczlwiy@holly.lan> <20200625103334.GO954398@dell> <20200626095405.nzhqsfjegj6qg2ro@holly.lan> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20200626095405.nzhqsfjegj6qg2ro@holly.lan> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Fri, 26 Jun 2020, Daniel Thompson wrote: > On Thu, Jun 25, 2020 at 11:33:34AM +0100, Lee Jones wrote: > > On Thu, 25 Jun 2020, Daniel Thompson wrote: > > > > > On Wed, Jun 24, 2020 at 03:57:16PM +0100, Lee Jones wrote: > > > > Kerneldoc syntax is used, but not complete. Descriptions required. > > > > > > > > Prevents warnings like: > > > > > > > > drivers/video/backlight/ili922x.c:116: warning: Function parameter or member 's' not described in 'CHECK_FREQ_REG' > > > > drivers/video/backlight/ili922x.c:116: warning: Function parameter or member 'x' not described in 'CHECK_FREQ_REG' > > > > > > > > Cc: > > > > Cc: Bartlomiej Zolnierkiewicz > > > > Cc: Software Engineering > > > > Signed-off-by: Lee Jones > > > > --- > > > > drivers/video/backlight/ili922x.c | 2 ++ > > > > 1 file changed, 2 insertions(+) > > > > > > > > diff --git a/drivers/video/backlight/ili922x.c b/drivers/video/backlight/ili922x.c > > > > index 9c5aa3fbb2842..8cb4b9d3c3bba 100644 > > > > --- a/drivers/video/backlight/ili922x.c > > > > +++ b/drivers/video/backlight/ili922x.c > > > > @@ -107,6 +107,8 @@ > > > > * lower frequency when the registers are read/written. > > > > * The macro sets the frequency in the spi_transfer structure if > > > > * the frequency exceeds the maximum value. > > > > + * @s: pointer to controller side proxy for an SPI slave device > > > > > > What's wrong with "a pointer to an SPI device"? > > > > > > I am aware, having looked it up to find out what the above actually > > > means, that this is how struct spi_device is described in its own kernel > > > doc but quoting at that level of detail of both overkill and confusing. > > > > I figured that using the official description would be better than > > making something up. However if you think it's better to KISS, then I > > can change it. > > Yes, I'd strongly prefer KISS here. > > I know it is an "I am the world" argument[1] but I found using such a > dogmatically accurate description out of context to be very confusing > and therefore I don't think such a comment improves readability. > > [1]: See #3 from http://www.leany.com/logic/Adams.html It's fine, you are the world, I get it. ;) Do you even like Country music? Will fix! -- Lee Jones [李琼斯] Senior Technical Lead - Developer Services Linaro.org │ Open source software for Arm SoCs Follow Linaro: Facebook | Twitter | Blog