Hi, On 03/02/20 14:27, Jean Delvare wrote: > 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@xxxxxxx> >>>> Reported-by: Lei YU <mine260309@xxxxxxxxx> >>>> Cc: Wolfram Sang <wsa@xxxxxxxxxxxxx> >>>> Cc: Luca Ceresoli <luca@xxxxxxxxxxxxxxxx> >>> >>> 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? 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. My 2c, -- Luca
