Re: [PATCH 10/10] iio: core: Clarify the modes

[Miquel Raynal <miquel.raynal@bootlin.com>]

Hi Jonathan,

jic23@kernel.org wrote on Sat, 5 Feb 2022 18:56:00 +0000:

> On Wed, 2 Feb 2022 14:46:35 +0100
> Miquel Raynal <miquel.raynal@bootlin.com> wrote:
> 
> > Hi Jonathan,
> > 
> > jic23@kernel.org wrote on Sat, 15 Jan 2022 17:30:50 +0000:
> >   
> > > On Wed, 15 Dec 2021 16:13:44 +0100
> > > Miquel Raynal <miquel.raynal@bootlin.com> wrote:
> > >     
> > > > As part of a previous discussion with Jonathan Cameron [1], it appeared
> > > > necessary to clarify the meaning of each mode so that new developers
> > > > could understand better what they should use or not use and when.
> > > > 
> > > > The idea of renaming these modes as been let aside because naming is a
> > > > big deal and requires a lot of thinking. So for now let's focus on
> > > > correctly explaining what each mode implies.
> > > > 
> > > > [1] https://lore.kernel.org/linux-iio/20210930165510.2295e6c4@jic23-huawei/
> > > > 
> > > > Suggested-by: Jonathan Cameron <jic23@kernel.org>
> > > > Signed-off-by: Miquel Raynal <miquel.raynal@bootlin.com>
> > > > ---
> > > >  include/linux/iio/iio.h | 40 +++++++++++++++++++++++++++++++++++++++-
> > > >  1 file changed, 39 insertions(+), 1 deletion(-)
> > > > 
> > > > diff --git a/include/linux/iio/iio.h b/include/linux/iio/iio.h
> > > > index d04ab89fa0c2..75b561fd63d0 100644
> > > > --- a/include/linux/iio/iio.h
> > > > +++ b/include/linux/iio/iio.h
> > > > @@ -314,7 +314,45 @@ static inline bool iio_channel_has_available(const struct iio_chan_spec *chan,
> > > >  s64 iio_get_time_ns(const struct iio_dev *indio_dev);
> > > >  unsigned int iio_get_time_res(const struct iio_dev *indio_dev);
> > > >  
> > > > -/* Device operating modes */
> > > > +/**
> > > > + * Device operating modes
> > > > + * @INDIO_DIRECT_MODE: There is an access to the last single value available.      
> > > 
> > > I'd avoid 'last' as not obvious wrt to what time point.  Perhaps use something
> > > horrible like "timely"?    
> > 
> > I don't feel a big difference between the two, besides timely being far
> > from easy to understand IMHO, but I'll use it if you think it's best.  
> timely is deliberately slightly vague.  An alternative would be to lay it out
> in detail
> 
> There is an access to either:
> a) The last single value available for devices that do not provide on demand
>    reads.
> b) A read of a new value is performed on demand.

I just get now why you refused the "last" wording.

That feels infinitely clearer. I'll wait for feedback on the second
version, and include these additional details.

[...]

> > V2 finally coming soon.  
> You beat me replying but I don't think any of the above replies will greatly influence things.
> 
> This wordy stuff always takes more thought that code so yet again you end
> up at the end of my review queue with these on the basis of too hard - I'll
> do it later :)

Take your time, you're not the only reviewer either.

Thanks,
Miquèl