Merge pull request #3301 from 0xc0170/fix_issue#2725

I2C - correct return values for write functions (docs) - part 1

drivers/I2C.h

@@ -117,8 +117,8 @@ public:
      *  @param repeated Repeated start, true - do not send stop at end
      *
      *  @returns
-     *       0 on success (ack),
-     *   non-0 on failure (nack)
+     *      0 or non-zero - written number of bytes,
+     *      negative - I2C_ERROR_XXX status
      */
     int write(int address, const char *data, int length, bool repeated = false);
 
@@ -127,8 +127,9 @@ public:
      *  @param data data to write out on bus
      *
      *  @returns
-     *    '1' if an ACK was received,
-     *    '0' otherwise
+     *    '0' - NAK was received
+     *    '1' - ACK was received,
+     *    '2' - timeout
      */
     int write(int data);
 

hal/i2c_api.h

@@ -117,7 +117,9 @@ int i2c_read(i2c_t *obj, int address, char *data, int length, int stop);
  *  @param data    The buffer for sending
  *  @param length  Number of bytes to write
  *  @param stop    Stop to be generated after the transfer is done
- *  @return Number of written bytes
+ *  @return 
+ *      zero or non-zero - Number of written bytes
+ *      negative - I2C_ERROR_XXX status
  */
 int i2c_write(i2c_t *obj, int address, const char *data, int length, int stop);