Re: [PATCH 6/6] dt-bindings: iio/adc: ingenic: add the JZ4760(B) socs to the sadc Documentation

[Jonathan Cameron <Jonathan.Cameron@Huawei.com>]

On Wed, 21 Jul 2021 20:17:45 +0100
Paul Cercueil <paul@crapouillou.net> wrote:

> Hi Christophe,
> 
> Please always add a short description in your patches, even if all you 
> do is repeat the patch title.
> 
> 
> Le mer., juil. 21 2021 at 12:53:17 +0200, citral23 
> <cbranchereau@gmail.com> a écrit :
> > Signed-off-by: citral23 <cbranchereau@gmail.com>
> > ---
> >  .../devicetree/bindings/iio/adc/ingenic,adc.yaml         | 9 
> > +++++++++
> >  1 file changed, 9 insertions(+)
> > 
> > diff --git 
> > a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml 
> > b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
> > index 433a3fb55a2e..1b423adba61d 100644
> > --- a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
> > +++ b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
> > @@ -23,6 +23,8 @@ properties:
> >      enum:
> >        - ingenic,jz4725b-adc
> >        - ingenic,jz4740-adc
> > +      - ingenic,jz4760-adc
> > +      - ingenic,jz4760b-adc
> >        - ingenic,jz4770-adc
> > 
> >    '#io-channel-cells':
> > @@ -43,6 +45,12 @@ properties:
> >    interrupts:
> >      maxItems: 1
> > 
> > +  ingenic,use-internal-divider:
> > +    description:
> > +      This property can be used to set VBAT_SEL in the JZ4760B CFG 
> > register
> > +      to sample the battery voltage from the internal divider. If 
> > absent, it
> > +      will sample the external divider.  
> 
> Please remove trailing spaces. And you don't need to describe internal 
> behaviour; you only need to explain the functionality in a user-facing 
> perspective. Something like:
> 
> "If present, battery voltage is read from the VBAT_IR pin, which has an 
> internal /4 divider. If absent, it is read through the VBAT_ER pin, 
> which does not have such divider."
> 
> You also don't specify the type of the property, please add "type: 
> boolean" before the description.
> 
> There should also be a way to make sure that this property can only be 
> used with the JZ4760B SoC. So a dependency for this vendor property on 
> the "ingenic,jz4760b-adc" compatible string. But I'm honestly not sure 
> how to express that... Maybe Rob can help.

Lots of examples in tree.
e.g.
https://elixir.bootlin.com/linux/v5.14-rc2/source/Documentation/devicetree/bindings/iio/st,st-sensors.yaml#L153

Basically you have an if block matching the compatible and for non matches
set it to false.  That combined with additionaProperties: false enforces
the property can't exist for those other devices.

> 
> > +
> >  required:
> >    - compatible
> >    - '#io-channel-cells'
> > @@ -53,6 +61,7 @@ required:
> > 
> >  additionalProperties: false
> > 
> > +  
> 
> Remove the extra newline.
> 
> Cheers,
> -Paul
> 
> >  examples:
> >    - |
> >      #include <dt-bindings/clock/jz4740-cgu.h>
> > --
> > 2.30.2
> >   
> 
>