Re: [PATCH 3/8] backlight: ili922x: Add missing kerneldoc descriptions for CHECK_FREQ_REG() args
From: Daniel Thompson <hidden>
Date: 2020-06-26 09:54:12
Also in:
dri-devel, linux-fbdev, lkml, stable
On Thu, Jun 25, 2020 at 11:33:34AM +0100, Lee Jones wrote:
On Thu, 25 Jun 2020, Daniel Thompson wrote:quoted
On Wed, Jun 24, 2020 at 03:57:16PM +0100, Lee Jones wrote:quoted
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: <redacted> Cc: Bartlomiej Zolnierkiewicz <redacted> Cc: Software Engineering <redacted> Signed-off-by: Lee Jones <redacted> --- 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 deviceWhat'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. Daniel. [1]: See #3 from http://www.leany.com/logic/Adams.html _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel