[PATCH] iio: imu: adis: fix all kernel-doc warnings in header file

[PATCH] iio: imu: adis: fix all kernel-doc warnings in header file

[Randy Dunlap]

Correct and add to adis.h to resolve all kernel-doc warnings:

- add a missing struct member description
- change one non-kernel-doc comment to use /* instead of /**
- correct function parameter @value to @val (7 locations)
- add function return value comments (13 locations)

Warning: include/linux/iio/imu/adis.h:97 struct member 'has_fifo'
 not described in 'adis_data'
Warning: include/linux/iio/imu/adis.h:139 Incorrect use of kernel-doc
 format: * The state_lock is meant to be used during operations that
 require
Warning: include/linux/iio/imu/adis.h:158 struct member '"__adis_"'
 not described in 'adis'
Warning: include/linux/iio/imu/adis.h:264 function parameter 'val'
 not described in 'adis_write_reg'
Warning: include/linux/iio/imu/adis.h:371 No description found for
 return value of 'adis_update_bits_base'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Jonathan Cameron <jic23@kernel.org>
Cc: David Lechner <dlechner@baylibre.com>
Cc: Nuno Sá <nuno.sa@analog.com>
Cc: Andy Shevchenko <andy@kernel.org>
Cc: linux-iio@vger.kernel.org
---
 include/linux/iio/imu/adis.h |   45 ++++++++++++++++++++++++++-------
 1 file changed, 36 insertions(+), 9 deletions(-)

--- linux-next-20251024.orig/include/linux/iio/imu/adis.h
+++ linux-next-20251024/include/linux/iio/imu/adis.h
@@ -57,6 +57,7 @@ struct adis_timeout {
  * @enable_irq: Hook for ADIS devices that have a special IRQ enable/disable
  * @unmasked_drdy: True for devices that cannot mask/unmask the data ready pin
  * @has_paging: True if ADIS device has paged registers
+ * @has_fifo: True if ADIS device has a hardware FIFO
  * @burst_reg_cmd:	Register command that triggers burst
  * @burst_len:		Burst size in the SPI RX buffer. If @burst_max_len is defined,
  *			this should be the minimum size supported by the device.
@@ -136,7 +137,7 @@ struct adis {
 	const struct adis_data	*data;
 	unsigned int		burst_extra_len;
 	const struct adis_ops	*ops;
-	/**
+	/*
 	 * The state_lock is meant to be used during operations that require
 	 * a sequence of SPI R/W in order to protect the SPI transfer
 	 * information (fields 'xfer', 'msg' & 'current_page') between
@@ -166,7 +167,7 @@ int __adis_reset(struct adis *adis);
  * adis_reset() - Reset the device
  * @adis: The adis device
  *
- * Returns 0 on success, a negative error code otherwise
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int adis_reset(struct adis *adis)
 {
@@ -183,7 +184,9 @@ int __adis_read_reg(struct adis *adis, u
  * __adis_write_reg_8() - Write single byte to a register (unlocked)
  * @adis: The adis device
  * @reg: The address of the register to be written
- * @value: The value to write
+ * @val: The value to write
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int __adis_write_reg_8(struct adis *adis, unsigned int reg,
 				     u8 val)
@@ -195,7 +198,9 @@ static inline int __adis_write_reg_8(str
  * __adis_write_reg_16() - Write 2 bytes to a pair of registers (unlocked)
  * @adis: The adis device
  * @reg: The address of the lower of the two registers
- * @value: Value to be written
+ * @val: Value to be written
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int __adis_write_reg_16(struct adis *adis, unsigned int reg,
 				      u16 val)
@@ -207,7 +212,9 @@ static inline int __adis_write_reg_16(st
  * __adis_write_reg_32() - write 4 bytes to four registers (unlocked)
  * @adis: The adis device
  * @reg: The address of the lower of the four register
- * @value: Value to be written
+ * @val: Value to be written
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int __adis_write_reg_32(struct adis *adis, unsigned int reg,
 				      u32 val)
@@ -220,6 +227,8 @@ static inline int __adis_write_reg_32(st
  * @adis: The adis device
  * @reg: The address of the lower of the two registers
  * @val: The value read back from the device
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int __adis_read_reg_16(struct adis *adis, unsigned int reg,
 				     u16 *val)
@@ -239,6 +248,8 @@ static inline int __adis_read_reg_16(str
  * @adis: The adis device
  * @reg: The address of the lower of the two registers
  * @val: The value read back from the device
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int __adis_read_reg_32(struct adis *adis, unsigned int reg,
 				     u32 *val)
@@ -257,8 +268,10 @@ static inline int __adis_read_reg_32(str
  * adis_write_reg() - write N bytes to register
  * @adis: The adis device
  * @reg: The address of the lower of the two registers
- * @value: The value to write to device (up to 4 bytes)
+ * @val: The value to write to device (up to 4 bytes)
  * @size: The size of the @value (in bytes)
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int adis_write_reg(struct adis *adis, unsigned int reg,
 				 unsigned int val, unsigned int size)
@@ -273,6 +286,8 @@ static inline int adis_write_reg(struct
  * @reg: The address of the lower of the two registers
  * @val: The value read back from the device
  * @size: The size of the @val buffer
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static int adis_read_reg(struct adis *adis, unsigned int reg,
 			 unsigned int *val, unsigned int size)
@@ -285,7 +300,9 @@ static int adis_read_reg(struct adis *ad
  * adis_write_reg_8() - Write single byte to a register
  * @adis: The adis device
  * @reg: The address of the register to be written
- * @value: The value to write
+ * @val: The value to write
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int adis_write_reg_8(struct adis *adis, unsigned int reg,
 				   u8 val)
@@ -297,7 +314,9 @@ static inline int adis_write_reg_8(struc
  * adis_write_reg_16() - Write 2 bytes to a pair of registers
  * @adis: The adis device
  * @reg: The address of the lower of the two registers
- * @value: Value to be written
+ * @val: Value to be written
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int adis_write_reg_16(struct adis *adis, unsigned int reg,
 				    u16 val)
@@ -309,7 +328,9 @@ static inline int adis_write_reg_16(stru
  * adis_write_reg_32() - write 4 bytes to four registers
  * @adis: The adis device
  * @reg: The address of the lower of the four register
- * @value: Value to be written
+ * @val: Value to be written
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int adis_write_reg_32(struct adis *adis, unsigned int reg,
 				    u32 val)
@@ -322,6 +343,8 @@ static inline int adis_write_reg_32(stru
  * @adis: The adis device
  * @reg: The address of the lower of the two registers
  * @val: The value read back from the device
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int adis_read_reg_16(struct adis *adis, unsigned int reg,
 				   u16 *val)
@@ -341,6 +364,8 @@ static inline int adis_read_reg_16(struc
  * @adis: The adis device
  * @reg: The address of the lower of the two registers
  * @val: The value read back from the device
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int adis_read_reg_32(struct adis *adis, unsigned int reg,
 				   u32 *val)
@@ -366,6 +391,8 @@ int __adis_update_bits_base(struct adis
  * @size: Size of the register to update
  *
  * Updates the desired bits of @reg in accordance with @mask and @val.
+ *
+ * Returns: %0 on success, a negative error code otherwise
  */
 static inline int adis_update_bits_base(struct adis *adis, unsigned int reg,
 					const u32 mask, const u32 val, u8 size)

Re: [PATCH] iio: imu: adis: fix all kernel-doc warnings in header file

[Andy Shevchenko]

On Sat, Oct 25, 2025 at 07:47:59PM -0700, Randy Dunlap wrote:
> Correct and add to adis.h to resolve all kernel-doc warnings:
> 
> - add a missing struct member description
> - change one non-kernel-doc comment to use /* instead of /**
> - correct function parameter @value to @val (7 locations)
> - add function return value comments (13 locations)
> 
> Warning: include/linux/iio/imu/adis.h:97 struct member 'has_fifo'
>  not described in 'adis_data'
> Warning: include/linux/iio/imu/adis.h:139 Incorrect use of kernel-doc
>  format: * The state_lock is meant to be used during operations that
>  require
> Warning: include/linux/iio/imu/adis.h:158 struct member '"__adis_"'
>  not described in 'adis'
> Warning: include/linux/iio/imu/adis.h:264 function parameter 'val'
>  not described in 'adis_write_reg'
> Warning: include/linux/iio/imu/adis.h:371 No description found for
>  return value of 'adis_update_bits_base'

Thanks for fixing all these, Randy!
Reviewed-by: Andy Shevchenko <andriy.shevchenko@intel.com>

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH] iio: imu: adis: fix all kernel-doc warnings in header file

[Nuno Sá]

On Sat, 2025-10-25 at 19:47 -0700, Randy Dunlap wrote:
> Correct and add to adis.h to resolve all kernel-doc warnings:
> 
> - add a missing struct member description
> - change one non-kernel-doc comment to use /* instead of /**
> - correct function parameter @value to @val (7 locations)
> - add function return value comments (13 locations)
> 
> Warning: include/linux/iio/imu/adis.h:97 struct member 'has_fifo'
>  not described in 'adis_data'
> Warning: include/linux/iio/imu/adis.h:139 Incorrect use of kernel-doc
>  format: * The state_lock is meant to be used during operations that
>  require
> Warning: include/linux/iio/imu/adis.h:158 struct member '"__adis_"'
>  not described in 'adis'
> Warning: include/linux/iio/imu/adis.h:264 function parameter 'val'
>  not described in 'adis_write_reg'
> Warning: include/linux/iio/imu/adis.h:371 No description found for
>  return value of 'adis_update_bits_base'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---

Thanks!

Reviewed-by: Nuno Sá <nuno.sa@analog.com>

> Cc: Jonathan Cameron <jic23@kernel.org>
> Cc: David Lechner <dlechner@baylibre.com>
> Cc: Nuno Sá <nuno.sa@analog.com>
> Cc: Andy Shevchenko <andy@kernel.org>
> Cc: linux-iio@vger.kernel.org
> ---
>  include/linux/iio/imu/adis.h |   45 ++++++++++++++++++++++++++-------
>  1 file changed, 36 insertions(+), 9 deletions(-)
> 
> --- linux-next-20251024.orig/include/linux/iio/imu/adis.h
> +++ linux-next-20251024/include/linux/iio/imu/adis.h
> @@ -57,6 +57,7 @@ struct adis_timeout {
>   * @enable_irq: Hook for ADIS devices that have a special IRQ enable/disable
>   * @unmasked_drdy: True for devices that cannot mask/unmask the data ready
> pin
>   * @has_paging: True if ADIS device has paged registers
> + * @has_fifo: True if ADIS device has a hardware FIFO
>   * @burst_reg_cmd:	Register command that triggers burst
>   * @burst_len:		Burst size in the SPI RX buffer. If @burst_max_len is
> defined,
>   *			this should be the minimum size supported by the
> device.
> @@ -136,7 +137,7 @@ struct adis {
>  	const struct adis_data	*data;
>  	unsigned int		burst_extra_len;
>  	const struct adis_ops	*ops;
> -	/**
> +	/*
>  	 * The state_lock is meant to be used during operations that require
>  	 * a sequence of SPI R/W in order to protect the SPI transfer
>  	 * information (fields 'xfer', 'msg' & 'current_page') between
> @@ -166,7 +167,7 @@ int __adis_reset(struct adis *adis);
>   * adis_reset() - Reset the device
>   * @adis: The adis device
>   *
> - * Returns 0 on success, a negative error code otherwise
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int adis_reset(struct adis *adis)
>  {
> @@ -183,7 +184,9 @@ int __adis_read_reg(struct adis *adis, u
>   * __adis_write_reg_8() - Write single byte to a register (unlocked)
>   * @adis: The adis device
>   * @reg: The address of the register to be written
> - * @value: The value to write
> + * @val: The value to write
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int __adis_write_reg_8(struct adis *adis, unsigned int reg,
>  				     u8 val)
> @@ -195,7 +198,9 @@ static inline int __adis_write_reg_8(str
>   * __adis_write_reg_16() - Write 2 bytes to a pair of registers (unlocked)
>   * @adis: The adis device
>   * @reg: The address of the lower of the two registers
> - * @value: Value to be written
> + * @val: Value to be written
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int __adis_write_reg_16(struct adis *adis, unsigned int reg,
>  				      u16 val)
> @@ -207,7 +212,9 @@ static inline int __adis_write_reg_16(st
>   * __adis_write_reg_32() - write 4 bytes to four registers (unlocked)
>   * @adis: The adis device
>   * @reg: The address of the lower of the four register
> - * @value: Value to be written
> + * @val: Value to be written
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int __adis_write_reg_32(struct adis *adis, unsigned int reg,
>  				      u32 val)
> @@ -220,6 +227,8 @@ static inline int __adis_write_reg_32(st
>   * @adis: The adis device
>   * @reg: The address of the lower of the two registers
>   * @val: The value read back from the device
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int __adis_read_reg_16(struct adis *adis, unsigned int reg,
>  				     u16 *val)
> @@ -239,6 +248,8 @@ static inline int __adis_read_reg_16(str
>   * @adis: The adis device
>   * @reg: The address of the lower of the two registers
>   * @val: The value read back from the device
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int __adis_read_reg_32(struct adis *adis, unsigned int reg,
>  				     u32 *val)
> @@ -257,8 +268,10 @@ static inline int __adis_read_reg_32(str
>   * adis_write_reg() - write N bytes to register
>   * @adis: The adis device
>   * @reg: The address of the lower of the two registers
> - * @value: The value to write to device (up to 4 bytes)
> + * @val: The value to write to device (up to 4 bytes)
>   * @size: The size of the @value (in bytes)
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int adis_write_reg(struct adis *adis, unsigned int reg,
>  				 unsigned int val, unsigned int size)
> @@ -273,6 +286,8 @@ static inline int adis_write_reg(struct
>   * @reg: The address of the lower of the two registers
>   * @val: The value read back from the device
>   * @size: The size of the @val buffer
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static int adis_read_reg(struct adis *adis, unsigned int reg,
>  			 unsigned int *val, unsigned int size)
> @@ -285,7 +300,9 @@ static int adis_read_reg(struct adis *ad
>   * adis_write_reg_8() - Write single byte to a register
>   * @adis: The adis device
>   * @reg: The address of the register to be written
> - * @value: The value to write
> + * @val: The value to write
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int adis_write_reg_8(struct adis *adis, unsigned int reg,
>  				   u8 val)
> @@ -297,7 +314,9 @@ static inline int adis_write_reg_8(struc
>   * adis_write_reg_16() - Write 2 bytes to a pair of registers
>   * @adis: The adis device
>   * @reg: The address of the lower of the two registers
> - * @value: Value to be written
> + * @val: Value to be written
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int adis_write_reg_16(struct adis *adis, unsigned int reg,
>  				    u16 val)
> @@ -309,7 +328,9 @@ static inline int adis_write_reg_16(stru
>   * adis_write_reg_32() - write 4 bytes to four registers
>   * @adis: The adis device
>   * @reg: The address of the lower of the four register
> - * @value: Value to be written
> + * @val: Value to be written
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int adis_write_reg_32(struct adis *adis, unsigned int reg,
>  				    u32 val)
> @@ -322,6 +343,8 @@ static inline int adis_write_reg_32(stru
>   * @adis: The adis device
>   * @reg: The address of the lower of the two registers
>   * @val: The value read back from the device
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int adis_read_reg_16(struct adis *adis, unsigned int reg,
>  				   u16 *val)
> @@ -341,6 +364,8 @@ static inline int adis_read_reg_16(struc
>   * @adis: The adis device
>   * @reg: The address of the lower of the two registers
>   * @val: The value read back from the device
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int adis_read_reg_32(struct adis *adis, unsigned int reg,
>  				   u32 *val)
> @@ -366,6 +391,8 @@ int __adis_update_bits_base(struct adis
>   * @size: Size of the register to update
>   *
>   * Updates the desired bits of @reg in accordance with @mask and @val.
> + *
> + * Returns: %0 on success, a negative error code otherwise
>   */
>  static inline int adis_update_bits_base(struct adis *adis, unsigned int reg,
>  					const u32 mask, const u32 val, u8
> size)

Re: [PATCH] iio: imu: adis: fix all kernel-doc warnings in header file

[Jonathan Cameron]

On Mon, 27 Oct 2025 13:03:54 +0000
Nuno Sá <noname.nuno@gmail.com> wrote:

> On Sat, 2025-10-25 at 19:47 -0700, Randy Dunlap wrote:
> > Correct and add to adis.h to resolve all kernel-doc warnings:
> > 
> > - add a missing struct member description
> > - change one non-kernel-doc comment to use /* instead of /**
> > - correct function parameter @value to @val (7 locations)
> > - add function return value comments (13 locations)
> > 
> > Warning: include/linux/iio/imu/adis.h:97 struct member 'has_fifo'
> >  not described in 'adis_data'
> > Warning: include/linux/iio/imu/adis.h:139 Incorrect use of kernel-doc
> >  format: * The state_lock is meant to be used during operations that
> >  require
> > Warning: include/linux/iio/imu/adis.h:158 struct member '"__adis_"'
> >  not described in 'adis'
> > Warning: include/linux/iio/imu/adis.h:264 function parameter 'val'
> >  not described in 'adis_write_reg'
> > Warning: include/linux/iio/imu/adis.h:371 No description found for
> >  return value of 'adis_update_bits_base'
> > 
> > Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> > ---  
> 
> Thanks!
> 
> Reviewed-by: Nuno Sá <nuno.sa@analog.com>

Applied.  Thanks.

Jonathan