Re: [PATCH 2/7] docs: iio: New docs for ad4062 driver

[Jonathan Cameron <jic23@kernel.org>]

> > > > > > +
> > > > > > +Device attributes
> > > > > > +=================
> > > > > > +
> > > > > > +The ADC contains only one channel with following attributes:
> > > > > > +
> > > > > > +.. list-table:: Channel attributes
> > > > > > +   :header-rows: 1
> > > > > > +
> > > > > > +   * - Attribute
> > > > > > +     - Description
> > > > > > +   * - ``in_voltage_calibscale``
> > > > > > +     - Sets the scale factor to multiply the raw value.    
> > > > > That's confusing.  This should be hardware 'tweak' to compensate for
> > > > > calibration or similar.  The text doesn't make it clear where that multiply
> > > > > is happening. Sounds too much like _scale.    
> > > > 
> > > > The user does raw * _scale * _calibscale to get the value in volts.  
> > > 
> > > That's not ABI compliant so no general purpose user space is going to do that.
> > > So a hard no for this being what userspace needs to apply.
> > > 
> > > I'm not particularly keen on calibscale for things other than tweaking so
> > > that raw * _scale is in milivolts.
> > > 
> > > Normally if we have other forms of controllable scaling it's a question
> > > of wrapping up any such scan factors into a writeable _scale.
> > >   
> > 
> > Ack, will update to raw * _scale, embedding the _calibscale into the
> > _scale value.
> >   
> 
> Fixup on my side, there is no need to "embed _calibscale into _scale".
> The only change that needs to be made is re-wording the doc to clarify
> that it is the hw that compensates for calibration errors:
> 
>     * - ``in_voltage_calibscale``
> -     - Sets the scale factor to multiply the raw value.
> +     - Sets the gain scaling factor that the hardware applies to the sample,
> +       to compensate for system gain error.
> 
> (datasheet p22, Gain Scaling)
> The mv reading is raw * _scale.

Good. That aligns with normal use of calibscale.

> 
> Best regards,
> Jorge