diff mbox series

[3/9] dt-bindings: iio: adc: adi,ad7606: improve descriptions

Message ID 20240618-cleanup-ad7606-v1-3-f1854d5c779d@baylibre.com (mailing list archive)
State Changes Requested
Headers show
Series iio: adc: ad7606: Improvements | expand

Commit Message

Guillaume Stols June 18, 2024, 2:02 p.m. UTC 
Reword a few descriptions, and normalize the text width to 80 characters.

Signed-off-by: Guillaume Stols <gstols@baylibre.com>
---
 .../devicetree/bindings/iio/adc/adi,ad7606.yaml    | 61 ++++++++++++----------
 1 file changed, 34 insertions(+), 27 deletions(-)

Comments

Jonathan Cameron June 23, 2024, 3:28 p.m. UTC | #1 
On Tue, 18 Jun 2024 14:02:35 +0000
Guillaume Stols <gstols@baylibre.com> wrote:

> Reword a few descriptions, and normalize the text width to 80 characters.

Don't rewrap text in a patch that does anything else as those real
changes are hidden.

Even if you are changing the text, minimise rewraps to those necessary
to avoid lines getting too long and fix them up in a follow up patch
that just rewraps.

I think most of the changes are fine, but it's really hard to spot
the real changes in here!

> 
> Signed-off-by: Guillaume Stols <gstols@baylibre.com>
> ---
>  .../devicetree/bindings/iio/adc/adi,ad7606.yaml    | 61 ++++++++++++----------
>  1 file changed, 34 insertions(+), 27 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
> index 00fdaed11cbd..80866940123c 100644
> --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
> +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
> @@ -36,64 +36,71 @@ properties:
>    avcc-supply: true
>  
>    interrupts:
> +    description:
> +      The BUSY pin falling edge indicates that the conversion is over, and thus
> +      new data is available.
>      maxItems: 1
>  
>    adi,conversion-start-gpios:
>      description:
> -      Must be the device tree identifier of the CONVST pin.
> -      This logic input is used to initiate conversions on the analog
> -      input channels. As the line is active high, it should be marked
> -      GPIO_ACTIVE_HIGH.
> +      Must be the device tree identifier of the CONVST pin(s). This logic input

Why plural when it has maxitems 1?

> +      is used to initiate conversions on the analog input channels. As the line
> +      is active high, it should be marked GPIO_ACTIVE_HIGH.

If you drop the plural change don't rewrap this in v2, it is unnecessary noise
that takes away from the real improvements.
>      maxItems: 1
>  
>    reset-gpios:
>      description:
> -      Must be the device tree identifier of the RESET pin. If specified,
> -      it will be asserted during driver probe. As the line is active high,
> -      it should be marked GPIO_ACTIVE_HIGH.
> +      Must be the device tree identifier of the RESET pin. If specified, it will
> +      be asserted during driver probe. On the AD7606x, as the line is active
> +      high, it should be marked GPIO_ACTIVE_HIGH. On the AD7616, as the line is
> +      active low, it should be marked GPIO_ACTIVE_LOW.
>      maxItems: 1


>  
>    adi,range-gpios:
>      description:
> -      Must be the device tree identifier of the RANGE pin. The polarity on
> -      this pin determines the input range of the analog input channels. If
> -      this pin is tied to a logic high, the analog input range is ±10V for
> -      all channels. If this pin is tied to a logic low, the analog input range
> +      Must be the device tree identifier of the RANGE pin. The state on this
> +      pin determines the input range of the analog input channels. If this pin
> +      is tied to a logic high, the analog input range is ±10V for all channels.
> +      On the AD760X, if this pin is tied to a logic low, the analog input range
>        is ±5V for all channels. As the line is active high, it should be marked
> -      GPIO_ACTIVE_HIGH.
> +      GPIO_ACTIVE_HIGH. On the AD7616, there are 2 pins, and if the 2 pins are
> +      tied to a logic high, software mode is enabled, otherwise one of the 3
> +      possible range values is selected.

With max items 1 how do we have 2?

>      maxItems: 1
>  
>    adi,oversampling-ratio-gpios:
>      description:
> -      Must be the device tree identifier of the over-sampling
> -      mode pins. As the line is active high, it should be marked
> -      GPIO_ACTIVE_HIGH.
> +      Must be the device tree identifier of the over-sampling mode pins. As the
> +      line is active high, it should be marked GPIO_ACTIVE_HIGH. On the AD7606X
> +      parts that support it, if all 3 pins are tied to a logic high, software
> +      mode is enabled.
>      maxItems: 3
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
index 00fdaed11cbd..80866940123c 100644
--- a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
+++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.yaml
@@ -36,64 +36,71 @@  properties:
   avcc-supply: true
 
   interrupts:
+    description:
+      The BUSY pin falling edge indicates that the conversion is over, and thus
+      new data is available.
     maxItems: 1
 
   adi,conversion-start-gpios:
     description:
-      Must be the device tree identifier of the CONVST pin.
-      This logic input is used to initiate conversions on the analog
-      input channels. As the line is active high, it should be marked
-      GPIO_ACTIVE_HIGH.
+      Must be the device tree identifier of the CONVST pin(s). This logic input
+      is used to initiate conversions on the analog input channels. As the line
+      is active high, it should be marked GPIO_ACTIVE_HIGH.
     maxItems: 1
 
   reset-gpios:
     description:
-      Must be the device tree identifier of the RESET pin. If specified,
-      it will be asserted during driver probe. As the line is active high,
-      it should be marked GPIO_ACTIVE_HIGH.
+      Must be the device tree identifier of the RESET pin. If specified, it will
+      be asserted during driver probe. On the AD7606x, as the line is active
+      high, it should be marked GPIO_ACTIVE_HIGH. On the AD7616, as the line is
+      active low, it should be marked GPIO_ACTIVE_LOW.
     maxItems: 1
 
   standby-gpios:
     description:
-      Must be the device tree identifier of the STBY pin. This pin is used
-      to place the AD7606 into one of two power-down modes, Standby mode or
+      Must be the device tree identifier of the STBY pin. This pin is used to
+      place the AD7606 into one of two power-down modes, Standby mode or
       Shutdown mode. As the line is active low, it should be marked
       GPIO_ACTIVE_LOW.
     maxItems: 1
 
   adi,first-data-gpios:
     description:
-      Must be the device tree identifier of the FRSTDATA pin.
-      The FRSTDATA output indicates when the first channel, V1, is
-      being read back on either the parallel, byte or serial interface.
-      As the line is active high, it should be marked GPIO_ACTIVE_HIGH.
+      Must be the device tree identifier of the FRSTDATA pin. The FRSTDATA
+      output indicates when the first channel, V1, is being read back on either
+      the parallel, byte or serial interface. As the line is active
+      high, it should be marked GPIO_ACTIVE_HIGH.
     maxItems: 1
 
   adi,range-gpios:
     description:
-      Must be the device tree identifier of the RANGE pin. The polarity on
-      this pin determines the input range of the analog input channels. If
-      this pin is tied to a logic high, the analog input range is ±10V for
-      all channels. If this pin is tied to a logic low, the analog input range
+      Must be the device tree identifier of the RANGE pin. The state on this
+      pin determines the input range of the analog input channels. If this pin
+      is tied to a logic high, the analog input range is ±10V for all channels.
+      On the AD760X, if this pin is tied to a logic low, the analog input range
       is ±5V for all channels. As the line is active high, it should be marked
-      GPIO_ACTIVE_HIGH.
+      GPIO_ACTIVE_HIGH. On the AD7616, there are 2 pins, and if the 2 pins are
+      tied to a logic high, software mode is enabled, otherwise one of the 3
+      possible range values is selected.
     maxItems: 1
 
   adi,oversampling-ratio-gpios:
     description:
-      Must be the device tree identifier of the over-sampling
-      mode pins. As the line is active high, it should be marked
-      GPIO_ACTIVE_HIGH.
+      Must be the device tree identifier of the over-sampling mode pins. As the
+      line is active high, it should be marked GPIO_ACTIVE_HIGH. On the AD7606X
+      parts that support it, if all 3 pins are tied to a logic high, software
+      mode is enabled.
     maxItems: 3
 
   adi,sw-mode:
     description:
-      Software mode of operation, so far available only for ad7616 and ad7606b.
-      It is enabled when all three oversampling mode pins are connected to
-      high level. The device is configured by the corresponding registers. If the
-      adi,oversampling-ratio-gpios property is defined, then the driver will set the
-      oversampling gpios to high. Otherwise, it is assumed that the pins are hardwired
-      to VDD.
+      Software mode of operation, so far available only for AD7616 and AD7606b.
+      It is enabled when all three oversampling mode pins are connected to high
+      level for the AD7606B, or all two range selection pins are connected to
+      high level for the AD7616. The device is configured by the corresponding
+      registers. If the adi,oversampling-ratio-gpios property is defined, then
+      the driver will set the oversampling gpios to high. Otherwise, it is
+      assumed that the pins are hardwired to VDD.
     type: boolean
 
 required: