Fixing serial buffer docs (#600)

* Fixing serial buffer docs

* updated shims

docs/reference/serial/read-buffer.md

@@ -1,6 +1,6 @@
 # Serial Read Buffer
 
-Read the buffered serial data as a buffer
+Read the buffered serial data as a buffer.
 
 ```sig
 serial.readBuffer(64);
@@ -8,5 +8,12 @@ serial.readBuffer(64);
 
 ## Returns
 
-* a Buffer containing input from the serial port. Empty if no data available.
+* a Buffer containing input from the serial port. The length of the buffer may be smaller than the requested length.
 
+## Remarks
+
+ 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.
+
+## See Also
+
+[micro:bit DAL documentation](https://lancaster-university.github.io/microbit-docs/ubit/serial/#managedstring-read-int-size-microbitserialmode-mode)

libs/core/_locales/core-jsdoc-strings.json

@@ -412,7 +412,7 @@
   "serial.delimiters": "Returns the delimiter corresponding string",
   "serial.onDataReceived": "Registers an event to be fired when one of the delimiter is matched.",
   "serial.onDataReceived|param|delimiters": "the characters to match received characters against.",
-  "serial.readBuffer": "Reads multiple characters from the receive buffer and fills a user buffer.",
+  "serial.readBuffer": "Reads multiple characters from the receive buffer. Pauses until enough characters are present.",
   "serial.readBuffer|param|length": "default buffer length, eg: 64",
   "serial.readLine": "Reads a line of text from the serial port.",
   "serial.readString": "Reads the buffered received data as a string",

libs/core/serial.cpp

@@ -121,7 +121,7 @@ namespace serial {
     }
 
     /**
-    * Reads multiple characters from the receive buffer and fills a user buffer.
+    * Reads multiple characters from the receive buffer. Pauses until enough characters are present.
     * @param length default buffer length, eg: 64
     */
     //% blockId=serial_readbuffer block="serial|read buffer %length"

libs/core/shims.d.ts

@@ -811,7 +811,7 @@ declare namespace serial {
     function writeBuffer(buffer: Buffer): void;
 
     /**
-     * Reads multiple characters from the receive buffer and fills a user buffer.
+     * Reads multiple characters from the receive buffer. Pauses until enough characters are present.
      * @param length default buffer length, eg: 64
      */
     //% blockId=serial_readbuffer block="serial|read buffer %length"