Add some descriptive info to serial docs (#704)

* Local commit

* Add some descriptive info to serial docs

* Example typo

* Tiny edit

docs/reference/serial/write-numbers.md

@@ -6,9 +6,17 @@ Write an array of numbers to the [serial](/device/serial) port.
 serial.writeNumbers([0, 1, 2]);
 ```
 
+Instead of writing a single number at a time using [write number](/reference/serial/write-number), you can write multiple numbers to the serial port at once. They are written as _Comma Separated Values (CSV)_.
+
+You can write the numbers `0` through `5` together and they will appear as one line of serial output:
+
+``0,1,2,3,4,5``
+
+This makes a line of CSV data where the commas between the numbers are the separators for each value.
+
 ## Parameters
 
-* `values` is the array of [number](/types/number) to write to the serial port
+* `values`: the array of [numbers](/types/number) to write to the serial port
 
 ## Example: one two three
 
@@ -23,7 +31,6 @@ basic.forever(() => {
 
 ## Example: plot temperature and light
 
-
 ```blocks
 serial.writeLine("temp,light")
 basic.forever(() => {
@@ -36,4 +43,3 @@ basic.forever(() => {
 [serial](/device/serial),
 [serial write line](/reference/serial/write-line),
 [serial write value](/reference/serial/write-value)
-

docs/reference/serial/write-value.md

@@ -1,19 +1,30 @@
-# Write Value
+# write Value
 
-Write a name/value pair and a newline character (`\r\n`) to the [serial](/device/serial) port.
+Write a **name:value** pair and a newline character (`\r\n`) to the [serial](/device/serial) port.
 
 ```sig
 serial.writeValue("x", 0);
 ```
 
+It is common when reporting or recording data to use a _Name Value Pair_ (NVP). They appear as a text output string in the form of a _name_ and a _value_ together. The name and the value are separated in the string with a _colon_, `:`. A name value pair reporting a temperature of `-15` degrees could look like:
+
+``temperature:-15``
+
+Associating a name with a value helps to identify related data when different data sources are recorded. For example, if you're reporting both temperature and light intensity, the _name:value_ format helps spreadsheets or other data analysis programs distingush between them and group the same types of values together properly. Reporting two data sources might look like this in the output:
+
+```
+temperature:-15
+temperature:-12
+light:154
+temperature:-11
+light:152
+```
+
 ## Parameters
 
 * `name` is the [string](/types/string) to write to the serial port
 * `value` is the [number](/types/number) to write to the serial port
 
-
-
-
 ## Example: streaming data
 
 Every 10 seconds, the example below sends the temperature and light level

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

@@ -409,26 +409,26 @@
   "pins.spiWrite": "Write to the SPI slave and return the response",
   "pins.spiWrite|param|value": "Data to be sent to the SPI slave",
   "serial": "Reading and writing data over a serial connection.",
-  "serial.delimiters": "Returns the delimiter corresponding string",
-  "serial.onDataReceived": "Registers an event to be fired when one of the delimiter is matched.",
+  "serial.delimiters": "Return the corresponding delimiter string",
+  "serial.onDataReceived": "Register 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": "Read multiple characters from the receive buffer. Pause 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",
-  "serial.readUntil": "Reads a line of text from the serial port and returns the buffer when the delimiter is met.",
+  "serial.readLine": "Read a line of text from the serial port.",
+  "serial.readString": "Read the buffered received data as a string",
+  "serial.readUntil": "Read a line of text from the serial port and return the buffer when the delimiter is met.",
   "serial.readUntil|param|delimiter": "text delimiter that separates each text chunk",
   "serial.redirect": "Set the serial input and output to use pins instead of the USB connection.",
   "serial.redirectToUSB": "Direct the serial input and output to use the USB connection.",
   "serial.redirect|param|rate": "the new baud rate. eg: 115200",
   "serial.redirect|param|rx": "the new reception pin, eg: SerialPin.P1",
   "serial.redirect|param|tx": "the new transmission pin, eg: SerialPin.P0",
-  "serial.writeBuffer": "Sends a buffer through Serial connection",
-  "serial.writeLine": "Prints a line of text to the serial",
-  "serial.writeNumber": "Prints a numeric value to the serial",
-  "serial.writeNumbers": "Prints an array of numeric values to the serial as CSV",
-  "serial.writeString": "Sends a piece of text through Serial connection.",
-  "serial.writeValue": "Writes a ``name: value`` pair line to the serial.",
+  "serial.writeBuffer": "Send a buffer through serial connection",
+  "serial.writeLine": "Print a line of text to the serial port",
+  "serial.writeNumber": "Print a numeric value to the serial port",
+  "serial.writeNumbers": "Print an array of numeric values as CSV to the serial port",
+  "serial.writeString": "Send a piece of text through the serial connection.",
+  "serial.writeValue": "Write a name:value pair as a line to the serial port.",
   "serial.writeValue|param|name": "name of the value stream, eg: x",
   "serial.writeValue|param|value": "to write"
 }

libs/core/serial.cpp

@@ -62,7 +62,7 @@ namespace serial {
     // note that at least one // followed by % is needed per declaration!
 
     /**
-     * Reads a line of text from the serial port and returns the buffer when the delimiter is met.
+     * Read a line of text from the serial port and return the buffer when the delimiter is met.
      * @param delimiter text delimiter that separates each text chunk
      */
     //% help=serial/read-until
@@ -73,7 +73,7 @@ namespace serial {
     }
 
     /**
-    * Reads the buffered received data as a string
+    * Read the buffered received data as a string
     */
     //% help=serial/read-string
     //% blockId=serial_read_buffer block="serial|read string"
@@ -85,7 +85,7 @@ namespace serial {
     }
 
     /**
-    * Registers an event to be fired when one of the delimiter is matched.
+    * Register an event to be fired when one of the delimiter is matched.
     * @param delimiters the characters to match received characters against.
     */
     //% help=serial/on-data-received
@@ -98,7 +98,7 @@ namespace serial {
     }
 
     /**
-     * Sends a piece of text through Serial connection.
+     * Send a piece of text through the serial connection.
      */
     //% help=serial/write-string
     //% weight=87 blockGap=8
@@ -110,7 +110,7 @@ namespace serial {
     }
 
     /**
-    * Sends a buffer through Serial connection
+    * Send a buffer through serial connection
     */
     //% blockId=serial_writebuffer block="serial|write buffer %buffer"
     //% help=serial/write-buffer advanced=true weight=6

libs/core/serial.ts

@@ -5,7 +5,7 @@
 //% advanced=true
 namespace serial {
     /**
-     * Prints a line of text to the serial
+     * Print a line of text to the serial port  
      * @param value to send over serial
      */
     //% weight=90
@@ -23,7 +23,7 @@ namespace serial {
     }
 
     /**
-     * Prints a numeric value to the serial
+     * Print a numeric value to the serial port
      */
     //% help=serial/write-number
     //% weight=89 blockGap=8
@@ -33,9 +33,9 @@ namespace serial {
     }
 
     /**
-     * Prints an array of numeric values to the serial as CSV
+     * Print an array of numeric values as CSV to the serial port
      */
-    //% help=serial-write-numbers
+    //% help=serial/write-numbers
     //% weight=86
     //% blockId=serial_writenumbers block="serial|write numbers %values"
     export function writeNumbers(values: number[]): void {
@@ -48,7 +48,7 @@ namespace serial {
     }
 
     /**
-     * Writes a ``name: value`` pair line to the serial.
+     * Write a name:value pair as a line to the serial port.
      * @param name name of the value stream, eg: x
      * @param value to write
      */
@@ -60,7 +60,7 @@ namespace serial {
     }
 
     /**
-     * Reads a line of text from the serial port.
+     * Read a line of text from the serial port.
      */
     //% help=serial/read-line
     //% blockId=serial_read_line block="serial|read line"
@@ -70,7 +70,7 @@ namespace serial {
     }
 
     /**
-     * Returns the delimiter corresponding string
+     * Return the corresponding delimiter string
      */
     //% blockId="serial_delimiter_conv" block="%del"
     //% weight=1 blockHidden=true

libs/core/shims.d.ts

@@ -772,7 +772,7 @@ declare namespace pins {
 declare namespace serial {
 
     /**
-     * Reads a line of text from the serial port and returns the buffer when the delimiter is met.
+     * Read a line of text from the serial port and return the buffer when the delimiter is met.
      * @param delimiter text delimiter that separates each text chunk
      */
     //% help=serial/read-until
@@ -781,7 +781,7 @@ declare namespace serial {
     function readUntil(delimiter: string): string;
 
     /**
-     * Reads the buffered received data as a string
+     * Read the buffered received data as a string
      */
     //% help=serial/read-string
     //% blockId=serial_read_buffer block="serial|read string"
@@ -789,7 +789,7 @@ declare namespace serial {
     function readString(): string;
 
     /**
-     * Registers an event to be fired when one of the delimiter is matched.
+     * Register an event to be fired when one of the delimiter is matched.
      * @param delimiters the characters to match received characters against.
      */
     //% help=serial/on-data-received
@@ -797,7 +797,7 @@ declare namespace serial {
     function onDataReceived(delimiters: string, body: () => void): void;
 
     /**
-     * Sends a piece of text through Serial connection.
+     * Send a piece of text through the serial connection.
      */
     //% help=serial/write-string
     //% weight=87 blockGap=8
@@ -805,7 +805,7 @@ declare namespace serial {
     function writeString(text: string): void;
 
     /**
-     * Sends a buffer through Serial connection
+     * Send a buffer through serial connection
      */
     //% blockId=serial_writebuffer block="serial|write buffer %buffer"
     //% help=serial/write-buffer advanced=true weight=6 shim=serial::writeBuffer