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 <[email protected]>
Reported-by: kernel test robot <[email protected]>
Cc: Lee Jones <[email protected]>
Cc: Daniel Thompson <[email protected]>
Cc: Jingoo Han <[email protected]>
Cc: [email protected]
Cc: Stefano Babic <[email protected]>
Cc: Anatolij Gustschin <[email protected]>
---
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
* @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
* 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.
@@ -145,6 +144,8 @@ struct ili922x {
* ili922x_read_status - read status register from display
* @spi: spi device
* @rs: output value
+ *
+ * Return: %0 on success or a negative error code on failure
*/
static int ili922x_read_status(struct spi_device *spi, u16 *rs)
{
@@ -188,6 +189,8 @@ static int ili922x_read_status(struct sp
* @spi: spi device
* @reg: offset of the register to be read
* @rx: output value
+ *
+ * Return: %0 on success or a negative error code on failure
*/
static int ili922x_read(struct spi_device *spi, u8 reg, u16 *rx)
{
@@ -242,6 +245,8 @@ static int ili922x_read(struct spi_devic
* @spi: struct spi_device *
* @reg: offset of the register to be written
* @value: value to be written
+ *
+ * Return: %0 on success or a negative error code on failure
*/
static int ili922x_write(struct spi_device *spi, u8 reg, u16 value)
{
@@ -348,6 +353,8 @@ static void set_write_to_gram_reg(struct
* The sequence to turn on the display is taken from
* the datasheet and/or the example code provided by the
* manufacturer.
+ *
+ * Return: %0 on success or a negative value on failure
*/
static int ili922x_poweron(struct spi_device *spi)
{
@@ -377,6 +384,8 @@ static int ili922x_poweron(struct spi_de
/**
* ili922x_poweroff - turn the display off
* @spi: spi device
+ *
+ * Return: %0 on success or a negative value on failure
*/
static int ili922x_poweroff(struct spi_device *spi)
{
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 <[email protected]>
> Reported-by: kernel test robot <[email protected]>
> Cc: Lee Jones <[email protected]>
> Cc: Daniel Thompson <[email protected]>
> Cc: Jingoo Han <[email protected]>
> Cc: [email protected]
> Cc: Stefano Babic <[email protected]>
> Cc: Anatolij Gustschin <[email protected]>
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.
On 11/15/21 3:38 AM, Daniel Thompson wrote:
>
> 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
>> /**
>> - * 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...
Got it. I'll send a v2.
Thanks.
--
~Randy