Add and update I2C topics (#602)

* Add and update I2C topics

* Throw in some edits for the serial buffer apis

* Add an example to serial read buffer

docs/reference/serial/read-buffer.md

@@ -1,19 +1,39 @@
-# Serial Read Buffer
+# read Buffer
 
-Read the buffered serial data as a buffer.
+Read available serial data into a buffer.
 
 ```sig
 serial.readBuffer(64);
 ```
 
+## Parameters
+
+* **length**: the [number](/types/number) of characters of serial data to read.
+
 ## Returns
 
-* a Buffer containing input from the serial port. The length of the buffer may be smaller than the requested length.
+* a [buffer](/types/buffer) containing input from the serial port. The length of the buffer may be smaller than the requested length.
 
-## Remarks
+## ~hint
+**Pause for more data**
 
- If the desired number of characters are available, this will return a string with the expected size. Otherwise, the calling fiber sleeps until the desired number of characters have been read.
+If the desired number of characters are available, **readBuffer** returns a buffer with the expected size. If not, the calling fiber (the part of your program calling the **readBuffer** function) sleeps until the desired number of characters are finally read into the buffer.
+
+The need to pause for more data is set by the @boardname@ **[serial mode](https://lancaster-university.github.io/microbit-docs/ubit/serial/#serial-modes)**.
+## ~
+
+## Example
+
+Read character data from the serial port one row at a time. Write the rows to an LED display connected to the I2C pins.
+
+```blocks
+let rowData: Buffer = null;
+for (let i = 0; i < 24; i++) {
+    rowData = serial.readBuffer(80);
+    pins.i2cWriteBuffer(65, rowData, false);
+}
+```
 
 ## See Also
 
-[micro:bit DAL documentation](https://lancaster-university.github.io/microbit-docs/ubit/serial/#managedstring-read-int-size-microbitserialmode-mode)
+[write buffer](/reference/serial/write-buffer)

docs/reference/serial/write-buffer.md

@@ -1,4 +1,4 @@
-# Serial Write Buffer
+# write Buffer
 
 Write a buffer to the [serial](/device/serial) port.
 
@@ -6,6 +6,22 @@ Write a buffer to the [serial](/device/serial) port.
 serial.writeBuffer(pins.createBuffer(0));
 ```
 
+You place your data characters into an existing buffer. All of the data, the length of the buffer, is written to the serial port.
+
 ## Parameters
 
-* `buffer` is the buffer to write to the serial port
+* **buffer**: a [buffer](/types/buffer) to write to the serial port.
+
+## Example
+
+Read some characters of data from a device connected to the I2C pins. Write the data to the serial port.
+
+```blocks
+pins.i2cWriteNumber(132, NumberFormat.UInt8LE, 0);
+let i2cBuffer = pins.i2cReadBuffer(132, 16, false);
+serial.writeBuffer(i2cBuffer);
+```
+
+## See also
+
+[read buffer](/reference/serial/read-buffer)