document the platform interface

[Peter A. Bigot]

Please provide better documentation on exactly what the platform read and write functions are given, and what they are expected to do.

It had never occurred to me that it's the responsibility of those functions to set the high bit of the provided reg to enable auto-increment before writing it to the bus, so that functions like lis2dh12_acceleration_raw_get() would return the full 3d acceleration data from registers 0x28 through 0x2d, rather than six copies of OUT_X_L.

[albezanc]

Thanks for your suggestion, surely the requirement of "automatic increment of the registration address" will be highlighted in the documentation.
Please, note that not all devices use the auto inc bit in the device address, so in my opinion, the best way is to refer to the examples.