Re: [PATCH 2/2] docs: i2c: dev-interface: document the actual implementation

[Jean Delvare <jdelvare@suse.de>]

Hi Luca, Wolfram,

On Thu, 23 Jan 2020 14:42:33 +0100, Luca Ceresoli wrote:
> On 23/01/20 12:09, Wolfram Sang wrote:
> > On Thu, Jan 23, 2020 at 11:11:37AM +0100, Jean Delvare wrote:  
> >> The old i2c-dev API based on inline functions is long gone, we have
> >> libi2c now which implements the same as real functions and comes with
> >> complete API documentation. Update the dev-interface documentation
> >> file accordingly to only mention what can be done without the
> >> library, and redirect the reader to the libi2c manual page for the
> >> rest.
> >>
> >> Signed-off-by: Jean Delvare <jdelvare@suse.de>
> >> Reported-by: Lei YU <mine260309@gmail.com>
> >> Cc: Wolfram Sang <wsa@the-dreams.de>
> >> Cc: Luca Ceresoli <luca@lucaceresoli.net>  
> > 
> > I wonder if we shouldn't move the 'C library'  paragraph before the 'C
> > example'? To make sure people are aware of it (and use it) early before
> > digging into the low-level C code?  
> 
> I agree, it would be better. For the rest it look good.

Hmmm. It's not like you can do everything with libi2c so you should
always use it. There are several things that can't be done with libi2c
so you will have to do them "manually". Anything that doesn't fit in the
SMBus specification basically. As a matter of fact, i2ctransfer does
not use libi2c.

Also, even when using libi2c, you still need to explicitly open the
device node, set the slave address, and close the device when you are
done (just seeing that's missing from the C example but it should be
added). So the C example is still relevant even if you use libi2c.

So I'm not sure swapping the sections makes that much sense. What would
help on the other hand is to add a pointer to the C library section at
the point of the C example where using the library would simplify the
code. Would that work for you?

-- 
Jean Delvare
SUSE L3 Support