Re: [PATCH] backlight: ili922x: fix kernel-doc warnings & notation

[Daniel Thompson <daniel.thompson@linaro.org>]

On Sun, Nov 14, 2021 at 07:39:25PM -0800, Randy Dunlap wrote:
> Convert function-like macro comments to kernel-doc notation and
> fix other kernel-doc warnings:
> 
> drivers/video/backlight/ili922x.c:85: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>     * START_BYTE(id, rs, rw)
> drivers/video/backlight/ili922x.c:118: warning: expecting prototype for CHECK_FREQ_REG(spi_device s, spi_transfer x)(). Prototype was for CHECK_FREQ_REG() instead
> 
> ili922x.c:92: warning: contents before sections
> ili922x.c:150: warning: No description found for return value of 'ili922x_read_status'
> ili922x.c:193: warning: No description found for return value of 'ili922x_read'
> ili922x.c:247: warning: No description found for return value of 'ili922x_write'
> ili922x.c:353: warning: No description found for return value of 'ili922x_poweron'
> ili922x.c:382: warning: No description found for return value of 'ili922x_poweroff'
> 
> Fixes: 4cfbfa971478 ("video: backlight: add ili922x lcd driver")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Reported-by: kernel test robot <lkp@intel.com>
> Cc: Lee Jones <lee.jones@linaro.org>
> Cc: Daniel Thompson <daniel.thompson@linaro.org>
> Cc: Jingoo Han <jingoohan1@gmail.com>
> Cc: dri-devel@lists.freedesktop.org
> Cc: Stefano Babic <sbabic@denx.de>
> Cc: Anatolij Gustschin <agust@denx.de>

Thanks for the fixes. Just a could of quibbles about full
stops/periods.


> ---
>  drivers/video/backlight/ili922x.c |   29 ++++++++++++++++++----------
>  1 file changed, 19 insertions(+), 10 deletions(-)
> 
> --- linux-next-20211102.orig/drivers/video/backlight/ili922x.c
> +++ linux-next-20211102/drivers/video/backlight/ili922x.c
> @@ -82,13 +82,7 @@
>  #define START_RW_READ		1
>  
>  /**
> - * START_BYTE(id, rs, rw)
> - *
> - * Set the start byte according to the required operation.
> - * The start byte is defined as:
> - *   ----------------------------------
> - *  | 0 | 1 | 1 | 1 | 0 | ID | RS | RW |
> - *   ----------------------------------
> + * START_BYTE() - Set the start byte according to the required operation

Missing full stop/period.


>   * @id: display's id as set by the manufacturer
>   * @rs: operation type bit, one of:
>   *	  - START_RS_INDEX	set the index register
> @@ -96,14 +90,19 @@
>   * @rw: read/write operation
>   *	 - START_RW_WRITE	write
>   *	 - START_RW_READ	read
> + *
> + * The start byte is defined as:
> + *   ----------------------------------
> + *  | 0 | 1 | 1 | 1 | 0 | ID | RS | RW |
> + *   ----------------------------------
>   */
>  #define START_BYTE(id, rs, rw)	\
>  	(0x70 | (((id) & 0x01) << 2) | (((rs) & 0x01) << 1) | ((rw) & 0x01))
>  
>  /**
> - * CHECK_FREQ_REG(spi_device s, spi_transfer x) - Check the frequency
> - *	for the SPI transfer. According to the datasheet, the controller
> - *	accept higher frequency for the GRAM transfer, but it requires
> + * CHECK_FREQ_REG() - Check the frequency for the SPI transfer
> + *	According to the datasheet, the controller
> + *	accepts higher frequency for the GRAM transfer, but it requires

Also missing the full stop/period in the first sentence of the summary.

Note that here the missing full stop does not benefit from a new line to
conceal it and we will generate bad text as a result.

  Check the frequency for the SPI transfer According to the data
  sheet, the controller accepts...


Daniel.