i2c: Kerneldoc for most I/O calls

Provide kerneldoc for most of the I2C and SMBus I/O calls.  Add a
comment summarizing some fault reporting issues which affect the
ability to provide clean fault reports through I2C master transfer
calls.  (Making it hard to precisely specify their return values...)

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: Jean Delvare <khali@linux-fr.org>