diff --git a/drivers/I2C.h b/drivers/I2C.h
index da09d943eb..84f1d89880 100644
--- a/drivers/I2C.h
+++ b/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);
 
diff --git a/hal/i2c_api.h b/hal/i2c_api.h
index 677596d0ed..41aef381d3 100644
--- a/hal/i2c_api.h
+++ b/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);