drivers: i2c: document slave API

The I2C slave API has been present since 1.12 but lacked documentation
on the behavior of its functions.  Provide that, and revise existing
documentation to make clear the type and mode of the device passed to
each API call.

Documented behavior is derived primarily from the LPC11U6X
implementation, as the STM32 implementation generally ignores return
values.

Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>