Re: [PATCH v4 3/3] docs: iio: add AD7191

[David Lechner <dlechner@baylibre.com>]

On 2/3/25 7:31 AM, Alisa-Dariana Roman wrote:
> Add documentation for AD7191 driver.
> 
> Signed-off-by: Alisa-Dariana Roman <alisa.roman@analog.com>
> ---
>  Documentation/iio/ad7191.rst | 250 +++++++++++++++++++++++++++++++++++
>  Documentation/iio/index.rst  |   1 +
>  2 files changed, 251 insertions(+)
>  create mode 100644 Documentation/iio/ad7191.rst
> 
> diff --git a/Documentation/iio/ad7191.rst b/Documentation/iio/ad7191.rst
> new file mode 100644
> index 000000000000..b55f3c13e45a
> --- /dev/null
> +++ b/Documentation/iio/ad7191.rst
> @@ -0,0 +1,250 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +==============
> +AD7191 driver
> +==============
> +
> +Device driver for Analog Devices AD7191 ADC.
> +
> +==================
> +Supported devices
> +==================
> +
> +* `AD7191 <https://www.analog.com/AD7191>`_
> +
> +The AD7191 is a high precision, low noise, 24-bit Σ-Δ ADC with integrated PGA.
> +It features two differential input channels, an internal temperature sensor, and
> +configurable sampling rates.
> +
> +=====================
> +Device Configuration
> +=====================
> +

I would call this section the `Devicetree/wiring` section since devicetree has
to do with how the chip is wired up.

The existing `Device Tree Bindings` section at the end pretty much just repeats
the DT bindings .yml doc, so we could drop that section from this doc.

What you have written in this section already covers it very well.

> +--------------------
> +Pin Configuration
> +--------------------

I think it looks the nicest when the --- exactly line up with the text and I
think that is the usual kernel style as well.

Example:

-----------------
Pin Configuration
-----------------

Same applies to the rest of the doc.


> +===================
> +Device Attributes
> +===================

There isn't really anything unusual about attributes on this chip compared to
typical ADCs, so I would be OK if we left out this section. If we do keep it
though, I think we should write out the full attribute name since some are
separate, some shared_by_type and some shared_by_all, so they have different
prefixes.

> +
> +The AD7191 provides several attributes through the IIO sysfs interface:
> +
> +-----------------------------------
> +Voltage Input Differential Channels
> +-----------------------------------
> +
> ++-------------------+----------------------------------------------------------+
> +| Attribute         | Description                                              |
> ++===================+==========================================================+
> +| raw               | Raw ADC output value                                     |
> ++-------------------+----------------------------------------------------------+
> +| scale             | Scale factor to convert raw value to voltage             |
> ++-------------------+----------------------------------------------------------+
> +| offset            | Voltage offset                                           |
> ++-------------------+----------------------------------------------------------+
> +| sampling_frequency| Current sampling frequency setting                       |
> ++-------------------+----------------------------------------------------------+
> +
> +--------------------
> +Temperature Sensor
> +--------------------
> +
> ++-------------------+----------------------------------------------------------+
> +| Attribute         | Description                                              |
> ++===================+==========================================================+
> +| raw               | Raw temperature sensor output value                      |
> ++-------------------+----------------------------------------------------------+
> +| scale             | Scale factor to convert raw value to temperature         |
> ++-------------------+----------------------------------------------------------+
> +| offset            | Temperature calibration offset                           |
> ++-------------------+----------------------------------------------------------+
> +
> +--------------------
> +Available Attributes
> +--------------------
> +
> +The following attributes show available configuration options:
> +
> +- sampling_frequency_available: List of supported sampling frequencies
> +- scale_available: List of supported scale factors (based on PGA settings)
> +

One of these days, we should probably write a generic page on the common
attributes raw/scale/offset and somewhat common sampling_frequency/
oversampling_ratio (probably a few more that I'm forgetting). :-)