diff --git a/drivers/I2C.h b/drivers/I2C.h
index c031d65b59..db3b505ae3 100644
--- a/drivers/I2C.h
+++ b/drivers/I2C.h
@@ -41,16 +41,32 @@ namespace mbed {
  *
  * Example:
  * @code
- * // Read from I2C slave at address 0x62
- *
+ * Read temperature from LM75BD
  * #include "mbed.h"
- *
- * I2C i2c(p28, p27);
+ * I2C i2c(I2C_SDA , I2C_SCL);
+ * const int addr7bit = 0x48;      // 7-bit I2C address
+ * const int addr8bit = 0x48 << 1; // 8-bit I2C address, 0x90
  *
  * int main() {
- *     int address = 0x62;
- *     char data[2];
- *     i2c.read(address, data, 2);
+ *     char cmd[2];
+ *     while (1) {
+ *         cmd[0] = 0x01;
+ *         cmd[1] = 0x00;
+ *
+ *         // read and write takes the 8-bit version of the address.
+ *         // set up configuration register (at 0x01)
+ *         i2c.write(addr8bit, cmd, 2);
+ *
+ *         wait(0.5);
+ *
+ *         // read temperature register
+ *         cmd[0] = 0x00;
+ *         i2c.write(addr8bit, cmd, 1);
+ *         i2c.read( addr8bit, cmd, 2);
+ *
+ *         float tmp = (float((cmd[0]<<8)|cmd[1]) / 256.0);
+ *         printf("Temp = %.2f\n", tmp);
+ *   }
  * }
  * @endcode
  * @ingroup drivers
@@ -92,10 +108,11 @@ public:
      *  @param data Pointer to the byte-array to read data in to
      *  @param length Number of bytes to read
      *  @param repeated Repeated start, true - don't send stop at end
+	 *         default value is false.
      *
      *  @returns
      *       0 on success (ack),
-     *   non-0 on failure (nack)
+     *       nonzero on failure (nack)
      */
     int read(int address, char *data, int length, bool repeated = false);
 
@@ -117,10 +134,11 @@ public:
      *  @param data Pointer to the byte-array data to send
      *  @param length Number of bytes to send
      *  @param repeated Repeated start, true - do not send stop at end
+	 *         default value is false.
      *
      *  @returns
      *       0 on success (ack),
-     *   non-0 on failure (nack)
+     *       nonzero on failure (nack)
      */
     int write(int address, const char *data, int length, bool repeated = false);
 
@@ -137,7 +155,6 @@ public:
 
     /** Creates a start condition on the I2C bus
      */
-
     void start(void);
 
     /** Creates a stop condition on the I2C bus
@@ -159,23 +176,25 @@ public:
 
 #if DEVICE_I2C_ASYNCH
 
-    /** Start non-blocking I2C transfer.
+    /** Start nonblocking I2C transfer.
      *
      * This function locks the deep sleep until any event has occurred
      *
      * @param address   8/10 bit I2C slave address
      * @param tx_buffer The TX buffer with data to be transfered
      * @param tx_length The length of TX buffer in bytes
-     * @param rx_buffer The RX buffer which is used for received data
+     * @param rx_buffer The RX buffer, which is used for received data
      * @param rx_length The length of RX buffer in bytes
      * @param event     The logical OR of events to modify
      * @param callback  The event callback function
      * @param repeated Repeated start, true - do not send stop at end
-     * @return Zero if the transfer has started, or -1 if I2C peripheral is busy
+	 *        default value is false.
+	 *
+     * @returns Zero if the transfer has started, or -1 if I2C peripheral is busy
      */
     int transfer(int address, const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length, const event_callback_t &callback, int event = I2C_EVENT_TRANSFER_COMPLETE, bool repeated = false);
 
-    /** Abort the on-going I2C transfer
+    /** Abort the ongoing I2C transfer
      */
     void abort_transfer();
 
@@ -193,6 +212,7 @@ protected:
     bool _deep_sleep_locked;
 #endif
 
+#if !defined(DOXYGEN_ONLY)
 protected:
     void aquire();
 
@@ -202,6 +222,7 @@ protected:
     static SingletonPtr<PlatformMutex> _mutex;
     PinName _sda;
     PinName _scl;
+#endif
 
 private:
     /** Recover I2C bus, when stuck with SDA low
@@ -210,7 +231,7 @@ private:
      *  @param sda I2C data line pin
      *  @param scl I2C clock line pin
      *
-     * @returns:
+     * @returns
      *    '0' - Successfully recovered
      *    'I2C_ERROR_BUS_BUSY' - In case of failure
      *