| Message ID | 20211115033925.22024-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | backlight: ili922x: fix kernel-doc warnings & notation | expand |
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.
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.
--- 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) {
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> --- drivers/video/backlight/ili922x.c | 29 ++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-)