Re: [RESEND PATCH v2 1/3] iio: Add some kerneldoc for channel types

[Randy Dunlap]

Hi Matti,

On 4/4/23 05:24, Matti Vaittinen wrote:
> For occasional contributor like me navigating the IIO channel types and
> modifiers may be a daunting task. One may have hard time finding out
> what type of channel should be used for device data and what units the
> data should be converted.
> 
> There is a great documentation for the sysfs interfaces though. What is
> missing is mapping of the channel types and modifiers to the sysfs
> documentation (and entries in documentation).
> 
> Give a hand to a driver writer by providing some documentation and by
> pointing to the sysfs document from the kernel doc of respective enums.
> 
> Signed-off-by: Matti Vaittinen <mazziesaccount@xxxxxxxxx>
> ---
> Changelog RFCv1 => v2:
> - add missing channel type docs provided by Jonathan
> - add @in front of member names and fix typos pointed by Andy
> - drop TODOs as Jonathan clarified the units
> 
> Initial discussion about these docs can be found from:
> https://lore.kernel.org/all/0e0d45b7-e582-82b2-9bac-1f70f9dad9f7@xxxxxxxxx/
> ---
>  include/uapi/linux/iio/types.h | 134 +++++++++++++++++++++++++++++++++
>  1 file changed, 134 insertions(+)
> 
> diff --git a/include/uapi/linux/iio/types.h b/include/uapi/linux/iio/types.h
> index c79f2f046a0b..78f4cfdc5e45 100644
> --- a/include/uapi/linux/iio/types.h
> +++ b/include/uapi/linux/iio/types.h
> @@ -11,6 +11,124 @@
>  #ifndef _UAPI_IIO_TYPES_H_
>  #define _UAPI_IIO_TYPES_H_
>  
> +/**
> + * iio_chan_type - Type of data transferred via IIO channel.

    * enum iio_chan_type - ...

as you did in patch 2/3.

> + *
...
> + */
>  enum iio_chan_type {
>  	IIO_VOLTAGE,
>  	IIO_CURRENT,
> @@ -49,6 +167,22 @@ enum iio_chan_type {
>  	IIO_MASSCONCENTRATION,
>  };
>  
> +/**
> + * iio_modifier - accurate class for channel data

Ditto here.

> + *
> + * @IIO_MOD_<X,Y,Z>:	Value represents <X,Y,Z>-axis data.
> + *			Typically used by channels of type:
> + *			IIO_ACCEL, IIO_TEMP, IIO_GRAVITY, IIO_POSITIONRELATIVE,
> + *			IIO_ANGL_VEL, IIO_INCLI, IIO_MAGN
> + * @IIO_MOD_LIGHT_BOTH:	Value contains visible and infrared light components
> + * @IIO_MOD_LIGHT_IR:	Value represents infrared radiation
> + * @IIO_MOD_LIGHT_<RED, GREEN, BLUE>:
> + *			Value represents visible <red, green, blue>  light
> + * @IIO_MOD_LIGHT_CLEAR:	Value represents all visible light frequencies
> + *
> + * Please find the detailed documentation for reported values from the
> + * Documentation/ABI/testing/sysfs-bus-iio.
> + */
>  enum iio_modifier {
>  	IIO_NO_MOD,
>  	IIO_MOD_X,

Thanks.
-- 
~Randy