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

[Jean Delvare <jdelvare@suse.de>]

Hi Luca,

On Mon, 3 Feb 2020 17:35:15 +0100, Luca Ceresoli wrote:
> On 03/02/20 14:27, Jean Delvare wrote:
> > 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?  
> 
> In my opinion we should first document the recommended way. Assuming
> libi2c is the recommended way for all uses it is capable of, that means
> documenting libi2c first.
> 
> Additionally, before documenting any of them I'd add a preamble similar
> to: "The I2C device can be accessed from user space either using the
> libi2c library or using low-level C functions directly. libi2c is more
> high-level but has limited functionality.". This is so it's clear to the
> reader from the beginning that there are two alternative approaches,
> whose explanation will follow.

Thank you for the suggested improvements, I agree they will make the
documentation easier to read. I'll integrate these changes in v2.

It might also make sense to add an example of the C library usage in
libi2c(3).

-- 
Jean Delvare
SUSE L3 Support